From 00a5cc4aaba205322d8c182ea0eae8912dee674f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:23:57 +0200
Subject: [PATCH 01/84] docs: align roadmap with current product state

---
 plans/README.md | 44 ++++++++++++++++++++++++++++++++------------
 1 file changed, 32 insertions(+), 12 deletions(-)

diff --git a/plans/README.md b/plans/README.md
index 66599ccf5..110278a8d 100644
--- a/plans/README.md
+++ b/plans/README.md
@@ -1,24 +1,44 @@
 # Plans
 
-This folder holds implementation plans for remaining DebateLab product work. Keep plans actionable: scope, files, data model, rollout steps, tests, and deployment notes.
+This folder tracks remaining DebateLab product work. The source tree is the authority: a plan is active only when it describes work that is not already present on the current branch.
 
-## Active Plans
+## NOW
+
+1. **Sparring v1** — turn DebateLab from a preparation toolbox into a repeatable training loop: motion → side → opponent exchange → qualitative scorecard → targeted next drill.
+2. **Verification loop** — keep PR CI deterministic, add browser coverage for the critical product journeys, and prepare authenticated staging E2E without applying or deploying any Supabase changes from this branch.
+3. **Post-remediation security validation** — verify the August security findings against current source and add regression tests around the remediated trust boundaries.
+
+## NEXT
+
+- [Ask and sitewide search quality](./search-quality.md): finish the remaining Exa domain-filter verification, handler-level integration coverage, and Factoids consulted-source UI.
+- Sparring follow-ups driven by product data: format presets, richer drills, voice/live-round experiments, and longitudinal progress only after the core loop proves useful.
+- Conversion and retention work based on measured activation and repeat usage.
+
+## LATER
 
 - [Admin announcements](./admin-announcements.md)
-- [Ask and sitewide search quality](./search-quality.md)
-- [Control honesty and deterministic toggles](./control-honesty.md)
-- [Debate sparring and streaming](./sparring-and-streaming.md)
-- [Model cost accounting](./model-cost-accounting.md)
-- [Prompt evaluation sheet (manual)](./prompt-eval-sheet.md)
-- [Quality & Truth release checklist](./release-checklist.md)
-- [Rate-limit UI cleanup](./rate-limit-ui-cleanup.md)
-- [Source auto-import](./source-auto-import.md)
-- [Streaming AI](./streaming-ai.md)
-- [System prompt improvement](./system-prompt-improvement.md)
 - [Animation polish](./animation-polish.md)
+- [Rate-limit UI cleanup](./rate-limit-ui-cleanup.md)
+- Further model/prompt experiments that are supported by evaluation data.
+
+## Historical / substantially implemented
+
+These files are kept for implementation history. Do not treat them as current instructions without checking the source tree first.
+
+- [Streaming AI](./streaming-ai.md) — Ask streaming endpoint/client/tests are already present.
+- [Source auto-import](./source-auto-import.md) — import endpoint, validation, schema, Library integration, and tests are already present.
+- [Control honesty and deterministic toggles](./control-honesty.md) — core enforcement is implemented and tested.
+- [Model cost accounting](./model-cost-accounting.md) — accounting helpers, audit metadata, and tests are present; remaining work is operational validation.
+- [System prompt improvement](./system-prompt-improvement.md) — layered shared prompt architecture is present.
+- [Quality & Truth release checklist](./release-checklist.md) — use as a release-history checklist, not a live roadmap.
+- [Supabase staging](./supabase-staging.md) and [Agent verification loop](./agent-verification-loop.md) — still useful design references, but any migration/function/secret deployment is explicitly out of scope for this feature branch.
 
 ## Done
 
 - [Bug and polish cleanup](./done/bugs.txt)
 - [Admin trial gifts](./done/admin-trial-gifts.md)
 - [Top users email fallback](./done/top-users-email-fallback.md)
+
+## Planning rule
+
+Every active plan should name scope, data ownership, rollout, automated verification, and what is deliberately not being changed. If implementation has landed, update this index in the same branch so agents do not repeatedly rediscover stale work.

From 354368c688d50dbf0d52b8323493eae524f1b188 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:24:12 +0200
Subject: [PATCH 02/84] feat: add sparring domain schemas

---
 src/lib/ai/schemas/sparring.ts | 72 ++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 src/lib/ai/schemas/sparring.ts

diff --git a/src/lib/ai/schemas/sparring.ts b/src/lib/ai/schemas/sparring.ts
new file mode 100644
index 000000000..71ccfe749
--- /dev/null
+++ b/src/lib/ai/schemas/sparring.ts
@@ -0,0 +1,72 @@
+import { z } from 'zod';
+
+export const SparringSideSchema = z.enum(['pro', 'con']);
+export const SparringDifficultySchema = z.enum(['beginner', 'competitive', 'brutal']);
+export const SparringTurnRoleSchema = z.enum(['user', 'ai']);
+export const SparringTurnPhaseSchema = z.enum(['opening', 'rebuttal']);
+
+export const SparringTurnSchema = z.object({
+  id: z.string().min(1),
+  role: SparringTurnRoleSchema,
+  phase: SparringTurnPhaseSchema,
+  content: z.string().min(1),
+  createdAt: z.number().finite(),
+});
+
+export const SparringSetupSchema = z.object({
+  motion: z.string().trim().min(8, 'Enter a complete debate motion.').max(1200),
+  side: SparringSideSchema,
+  difficulty: SparringDifficultySchema,
+  useActiveSources: z.boolean().default(true),
+});
+
+export const SparringOpponentOutputSchema = z.object({
+  speech: z.string().trim().min(1),
+  pressurePoints: z.array(z.string().trim().min(1)).max(4).default([]),
+});
+
+export const SparringRatingSchema = z.enum(['needs-work', 'solid', 'strong']);
+
+export const SparringCategoryFeedbackSchema = z.object({
+  category: z.enum([
+    'argument-strength',
+    'warrant-quality',
+    'impact-analysis',
+    'engagement',
+    'rebuttal-efficiency',
+    'weighing',
+    'evidence-use',
+    'strategy',
+  ]),
+  rating: SparringRatingSchema,
+  evidence: z.string().trim().min(1),
+  advice: z.string().trim().min(1),
+});
+
+export const SparringScorecardSchema = z.object({
+  verdict: z.enum(['user-edge', 'ai-edge', 'close']),
+  summary: z.string().trim().min(1),
+  biggestImprovement: z.string().trim().min(1),
+  strengths: z.array(z.string().trim().min(1)).max(5).default([]),
+  missedArguments: z.array(z.string().trim().min(1)).max(5).default([]),
+  categories: z.array(SparringCategoryFeedbackSchema).min(4).max(8),
+  nextDrill: z.string().trim().min(1),
+});
+
+export const SparringSessionSchema = z.object({
+  id: z.string().min(1),
+  setup: SparringSetupSchema,
+  turns: z.array(SparringTurnSchema).max(8),
+  scorecard: SparringScorecardSchema.optional(),
+  status: z.enum(['active', 'complete']),
+  createdAt: z.number().finite(),
+  updatedAt: z.number().finite(),
+});
+
+export type SparringSide = z.infer<typeof SparringSideSchema>;
+export type SparringDifficulty = z.infer<typeof SparringDifficultySchema>;
+export type SparringTurn = z.infer<typeof SparringTurnSchema>;
+export type SparringSetup = z.infer<typeof SparringSetupSchema>;
+export type SparringOpponentOutput = z.infer<typeof SparringOpponentOutputSchema>;
+export type SparringScorecard = z.infer<typeof SparringScorecardSchema>;
+export type SparringSession = z.infer<typeof SparringSessionSchema>;

From c1173840d0059d7c47979a8f5cd19c5a11ddbbf3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:24:37 +0200
Subject: [PATCH 03/84] feat: add local-first sparring history store

---
 src/lib/stores/sparring-store.ts | 99 ++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 src/lib/stores/sparring-store.ts

diff --git a/src/lib/stores/sparring-store.ts b/src/lib/stores/sparring-store.ts
new file mode 100644
index 000000000..229920f09
--- /dev/null
+++ b/src/lib/stores/sparring-store.ts
@@ -0,0 +1,99 @@
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+import type {
+  SparringScorecard,
+  SparringSession,
+  SparringSetup,
+  SparringTurn,
+} from '@/lib/ai/schemas/sparring';
+
+const MAX_SAVED_SESSIONS = 30;
+
+function makeId(prefix: string) {
+  return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+interface SparringState {
+  sessions: SparringSession[];
+  activeSessionId: string | null;
+  startSession: (setup: SparringSetup) => SparringSession;
+  addTurn: (sessionId: string, turn: Omit<SparringTurn, 'id' | 'createdAt'>) => SparringTurn;
+  completeSession: (sessionId: string, scorecard: SparringScorecard) => void;
+  setActiveSession: (sessionId: string | null) => void;
+  deleteSession: (sessionId: string) => void;
+  clearSparringHistory: () => void;
+}
+
+export const useSparringStore = create<SparringState>()(
+  persist(
+    (set, get) => ({
+      sessions: [],
+      activeSessionId: null,
+
+      startSession: (setup) => {
+        const now = Date.now();
+        const session: SparringSession = {
+          id: makeId('spar'),
+          setup,
+          turns: [],
+          status: 'active',
+          createdAt: now,
+          updatedAt: now,
+        };
+        set((state) => ({
+          sessions: [session, ...state.sessions].slice(0, MAX_SAVED_SESSIONS),
+          activeSessionId: session.id,
+        }));
+        return session;
+      },
+
+      addTurn: (sessionId, turn) => {
+        const created: SparringTurn = {
+          ...turn,
+          id: makeId('turn'),
+          createdAt: Date.now(),
+        };
+        set((state) => ({
+          sessions: state.sessions.map((session) => session.id === sessionId
+            ? { ...session, turns: [...session.turns, created], updatedAt: Date.now() }
+            : session),
+        }));
+        return created;
+      },
+
+      completeSession: (sessionId, scorecard) => {
+        set((state) => ({
+          sessions: state.sessions.map((session) => session.id === sessionId
+            ? { ...session, scorecard, status: 'complete', updatedAt: Date.now() }
+            : session),
+        }));
+      },
+
+      setActiveSession: (activeSessionId) => set({ activeSessionId }),
+
+      deleteSession: (sessionId) => set((state) => ({
+        sessions: state.sessions.filter((session) => session.id !== sessionId),
+        activeSessionId: state.activeSessionId === sessionId ? null : state.activeSessionId,
+      })),
+
+      clearSparringHistory: () => set({ sessions: [], activeSessionId: null }),
+    }),
+    {
+      name: 'debatelab-sparring',
+      partialize: (state) => ({ sessions: state.sessions, activeSessionId: state.activeSessionId }),
+      merge: (persisted, current) => {
+        const saved = persisted as Partial<SparringState> | undefined;
+        const sessions = Array.isArray(saved?.sessions) ? saved.sessions.slice(0, MAX_SAVED_SESSIONS) : [];
+        const activeSessionId = typeof saved?.activeSessionId === 'string' && sessions.some((session) => session.id === saved.activeSessionId)
+          ? saved.activeSessionId
+          : null;
+        return { ...current, ...saved, sessions, activeSessionId } as SparringState;
+      },
+    },
+  ),
+);
+
+export function getSparringSession(sessionId: string | null): SparringSession | null {
+  if (!sessionId) return null;
+  return useSparringStore.getState().sessions.find((session) => session.id === sessionId) ?? null;
+}

From 2876b9ab0023e12f0ea87b4c6214d072ff629608 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:25:13 +0200
Subject: [PATCH 04/84] feat: add grounded sparring AI client

---
 src/lib/ai/sparring-client.ts | 159 ++++++++++++++++++++++++++++++++++
 1 file changed, 159 insertions(+)
 create mode 100644 src/lib/ai/sparring-client.ts

diff --git a/src/lib/ai/sparring-client.ts b/src/lib/ai/sparring-client.ts
new file mode 100644
index 000000000..324b5277e
--- /dev/null
+++ b/src/lib/ai/sparring-client.ts
@@ -0,0 +1,159 @@
+import { askChat, AIResponseError } from '@/lib/ai/client';
+import type { ProviderConfig } from '@/lib/ai/providers/types';
+import {
+  SparringOpponentOutputSchema,
+  SparringScorecardSchema,
+  type SparringOpponentOutput,
+  type SparringScorecard,
+  type SparringSession,
+  type SparringTurn,
+} from '@/lib/ai/schemas/sparring';
+
+function opposingSide(side: 'pro' | 'con') {
+  return side === 'pro' ? 'con' : 'pro';
+}
+
+function difficultyInstruction(difficulty: SparringSession['setup']['difficulty']) {
+  switch (difficulty) {
+    case 'beginner':
+      return 'Argue clearly and realistically. Pressure obvious gaps, but do not use obscure theory or intentionally tricky framing.';
+    case 'brutal':
+      return 'Argue like a strong elimination-round opponent. Exploit dropped warrants, force comparative weighing, and punish unsupported assertions. Stay fair and do not invent evidence.';
+    case 'competitive':
+    default:
+      return 'Argue like a competent tournament opponent. Directly engage the user, develop warrants, and create clear clash without manufacturing facts.';
+  }
+}
+
+function transcript(turns: SparringTurn[]) {
+  return turns.map((turn, index) => {
+    const speaker = turn.role === 'user' ? 'USER' : 'AI OPPONENT';
+    return `${index + 1}. ${speaker} (${turn.phase.toUpperCase()}):\n${turn.content}`;
+  }).join('\n\n');
+}
+
+function extractJsonObject(text: string): unknown {
+  const trimmed = text.trim();
+  const unfenced = trimmed
+    .replace(/^```(?:json)?\s*/i, '')
+    .replace(/\s*```$/i, '')
+    .trim();
+
+  try {
+    return JSON.parse(unfenced);
+  } catch {
+    const start = unfenced.indexOf('{');
+    const end = unfenced.lastIndexOf('}');
+    if (start >= 0 && end > start) {
+      return JSON.parse(unfenced.slice(start, end + 1));
+    }
+    throw new Error('No JSON object found');
+  }
+}
+
+function opponentPrompt(session: SparringSession, userSpeech: string) {
+  const aiSide = opposingSide(session.setup.side);
+  return `You are the opponent in a DebateLab sparring round.
+
+Motion: ${session.setup.motion}
+User side: ${session.setup.side}
+Your side: ${aiSide}
+Difficulty: ${session.setup.difficulty}
+Difficulty instruction: ${difficultyInstruction(session.setup.difficulty)}
+
+Round transcript so far:
+${transcript(session.turns)}
+
+The user's newest speech is:
+${userSpeech}
+
+Respond to the user's actual arguments, not a generic version of the motion. Do not invent facts, quotations, statistics, studies, or sources. If the user's claim lacks support, attack the missing warrant instead of fabricating counter-evidence. Make the speech usable in a real round and keep it under 550 words.
+
+Inside your normal DebateLab response field, return ONLY this JSON object and no markdown fences:
+{
+  "speech": "the opponent speech",
+  "pressurePoints": ["up to four specific vulnerabilities in the user's latest speech"]
+}`;
+}
+
+function scorecardPrompt(session: SparringSession) {
+  return `Judge this completed DebateLab sparring round as a demanding but fair debate coach.
+
+Motion: ${session.setup.motion}
+User side: ${session.setup.side}
+AI opponent side: ${opposingSide(session.setup.side)}
+Difficulty: ${session.setup.difficulty}
+Active Source Library grounding was ${session.setup.useActiveSources ? 'enabled' : 'not requested'} for the round.
+
+FULL TRANSCRIPT:
+${transcript(session.turns)}
+
+Evaluate only what appears in the transcript. Do not pretend the user cited evidence they did not cite. Do not infer delivery, tone of voice, eye contact, speaking speed, or other audio qualities from typed text. For every category, point to a specific argument, omission, comparison, or response from the transcript. Scores are deliberately qualitative because false numeric precision is not useful here.
+
+Inside your normal DebateLab response field, return ONLY this JSON object and no markdown fences:
+{
+  "verdict": "user-edge | ai-edge | close",
+  "summary": "short judge-style explanation of the round",
+  "biggestImprovement": "the single highest-leverage change for the user's next round",
+  "strengths": ["specific strengths, maximum five"],
+  "missedArguments": ["arguments, responses, or weighing opportunities the user missed, maximum five"],
+  "categories": [
+    { "category": "argument-strength", "rating": "needs-work | solid | strong", "evidence": "specific transcript evidence", "advice": "concrete improvement" },
+    { "category": "warrant-quality", "rating": "needs-work | solid | strong", "evidence": "specific transcript evidence", "advice": "concrete improvement" },
+    { "category": "impact-analysis", "rating": "needs-work | solid | strong", "evidence": "specific transcript evidence", "advice": "concrete improvement" },
+    { "category": "engagement", "rating": "needs-work | solid | strong", "evidence": "specific transcript evidence", "advice": "concrete improvement" },
+    { "category": "rebuttal-efficiency", "rating": "needs-work | solid | strong", "evidence": "specific transcript evidence", "advice": "concrete improvement" },
+    { "category": "weighing", "rating": "needs-work | solid | strong", "evidence": "specific transcript evidence", "advice": "concrete improvement" },
+    { "category": "evidence-use", "rating": "needs-work | solid | strong", "evidence": "specific transcript evidence", "advice": "concrete improvement" },
+    { "category": "strategy", "rating": "needs-work | solid | strong", "evidence": "specific transcript evidence", "advice": "concrete improvement" }
+  ],
+  "nextDrill": "one focused drill the user can do immediately"
+}`;
+}
+
+async function askForJson(prompt: string, config: ProviderConfig) {
+  const output = await askChat(prompt, [], 'general', config, {
+    citationMode: false,
+    webSearch: false,
+    prosConsMode: false,
+    argumentMapMode: false,
+  });
+  return output.response;
+}
+
+export async function requestSparringOpponent(
+  session: SparringSession,
+  userSpeech: string,
+  config: ProviderConfig,
+): Promise<SparringOpponentOutput> {
+  const response = await askForJson(opponentPrompt(session, userSpeech), config);
+  try {
+    return SparringOpponentOutputSchema.parse(extractJsonObject(response));
+  } catch {
+    // A plain-text opponent speech is still useful and safer than discarding a
+    // successful provider response because it ignored the inner JSON request.
+    const speech = response.trim();
+    if (speech) return { speech, pressurePoints: [] };
+    throw new AIResponseError('The sparring opponent returned an empty response.');
+  }
+}
+
+export async function requestSparringScorecard(
+  session: SparringSession,
+  config: ProviderConfig,
+): Promise<SparringScorecard> {
+  const first = await askForJson(scorecardPrompt(session), config);
+  try {
+    return SparringScorecardSchema.parse(extractJsonObject(first));
+  } catch {
+    const repairPrompt = `${scorecardPrompt(session)}\n\nYour previous response could not be parsed as the requested scorecard. Re-evaluate from the transcript and return the raw JSON object only. Do not add prose or markdown fences.`;
+    const repaired = await askForJson(repairPrompt, config);
+    try {
+      return SparringScorecardSchema.parse(extractJsonObject(repaired));
+    } catch (error) {
+      throw new AIResponseError('The sparring scorecard did not match the expected schema.', {
+        details: { cause: error instanceof Error ? error.message : String(error) },
+      });
+    }
+  }
+}

From 8bc104d76e8c8c7bc63a20310b5524fbc492b7cf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:25:50 +0200
Subject: [PATCH 05/84] feat: add sparring model configuration

---
 src/lib/stores/settings-store.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/lib/stores/settings-store.ts b/src/lib/stores/settings-store.ts
index e80581b83..4b9b15e81 100644
--- a/src/lib/stores/settings-store.ts
+++ b/src/lib/stores/settings-store.ts
@@ -4,7 +4,7 @@ import i18n from '@/i18n';
 import type { ProviderConfig } from '../ai/providers/types';
 import { supabase } from '@/lib/supabase/client';
 
-export type FeatureTab = 'generate' | 'attack' | 'brainstorm' | 'factoids' | 'ask';
+export type FeatureTab = 'generate' | 'attack' | 'brainstorm' | 'factoids' | 'ask' | 'sparring';
 
 interface SettingsState {
   language: 'en' | 'es' | 'hu';
@@ -37,6 +37,7 @@ const getDefaultFeatureConfigs = (): Record<FeatureTab, ProviderConfig> => ({
   brainstorm: { ...defaultConfig, temperature: 0.9 },
   factoids: { ...defaultConfig, temperature: 0.3 },
   ask: { ...defaultConfig },
+  sparring: { ...defaultConfig, temperature: 0.75 },
 });
 
 function normalizeFeatureConfigs(configs: unknown): Record<FeatureTab, ProviderConfig> {
@@ -207,4 +208,4 @@ export const useSettingsStore = create<SettingsState>()(
       },
     }
   )
-);
+);
\ No newline at end of file

From 05165a52d35031ca27c4da09ff997cc9e91b4185 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:26:18 +0200
Subject: [PATCH 06/84] feat: add sparring setup UI

---
 .../features/sparring/SparringSetup.tsx       | 168 ++++++++++++++++++
 1 file changed, 168 insertions(+)
 create mode 100644 src/components/features/sparring/SparringSetup.tsx

diff --git a/src/components/features/sparring/SparringSetup.tsx b/src/components/features/sparring/SparringSetup.tsx
new file mode 100644
index 000000000..76fc32b5e
--- /dev/null
+++ b/src/components/features/sparring/SparringSetup.tsx
@@ -0,0 +1,168 @@
+import { useMemo, useState } from 'react';
+import { BookOpenCheck, Shield, Sparkles, Swords, Zap } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { Label } from '@/components/ui/label';
+import { Switch } from '@/components/ui/switch';
+import { Textarea } from '@/components/ui/textarea';
+import { ModelSelector } from '@/components/ModelSelector';
+import { cn } from '@/lib/utils';
+import { useSessionStore } from '@/lib/stores/session-store';
+import { SparringSetupSchema, type SparringDifficulty, type SparringSetup } from '@/lib/ai/schemas/sparring';
+
+interface SparringSetupProps {
+  onStart: (setup: SparringSetup) => void;
+  isStarting?: boolean;
+  defaultMotion?: string;
+}
+
+const difficulties: Array<{
+  id: SparringDifficulty;
+  label: string;
+  description: string;
+  icon: typeof Shield;
+}> = [
+  {
+    id: 'beginner',
+    label: 'Beginner',
+    description: 'Clear clash and forgiving pressure. Good for drilling fundamentals.',
+    icon: Shield,
+  },
+  {
+    id: 'competitive',
+    label: 'Competitive',
+    description: 'A competent tournament opponent that directly engages your case.',
+    icon: Swords,
+  },
+  {
+    id: 'brutal',
+    label: 'Brutal',
+    description: 'Elimination-round pressure. Dropped warrants and weak weighing get punished.',
+    icon: Zap,
+  },
+];
+
+export function SparringSetup({ onStart, isStarting = false, defaultMotion = '' }: SparringSetupProps) {
+  const [motion, setMotion] = useState(defaultMotion);
+  const [side, setSide] = useState<'pro' | 'con'>('pro');
+  const [difficulty, setDifficulty] = useState<SparringDifficulty>('competitive');
+  const [useActiveSources, setUseActiveSources] = useState(true);
+  const activeSourceCount = useSessionStore((state) => state.sourceLibrary.filter((source) => source.isActive).length);
+
+  const validation = useMemo(() => SparringSetupSchema.safeParse({ motion, side, difficulty, useActiveSources }), [motion, side, difficulty, useActiveSources]);
+
+  const handleStart = () => {
+    if (!validation.success) return;
+    onStart(validation.data);
+  };
+
+  return (
+    <div className="grid gap-6 lg:grid-cols-[1fr_340px]">
+      <Card className="border-border/70 bg-card/70">
+        <CardHeader>
+          <div className="flex items-center gap-3">
+            <div className="flex h-10 w-10 items-center justify-center rounded-lg bg-primary/10 text-primary">
+              <Sparkles className="h-5 w-5" />
+            </div>
+            <div>
+              <CardTitle>Set up a round</CardTitle>
+              <CardDescription>Start small: two speeches from you, two from the AI, then an evidence-backed scorecard.</CardDescription>
+            </div>
+          </div>
+        </CardHeader>
+        <CardContent className="space-y-6">
+          <div className="space-y-2">
+            <Label htmlFor="sparring-motion">Motion</Label>
+            <Textarea
+              id="sparring-motion"
+              value={motion}
+              onChange={(event) => setMotion(event.target.value)}
+              placeholder="This House would ban targeted advertising to minors."
+              className="min-h-28 resize-y"
+              maxLength={1200}
+            />
+            <div className="flex items-center justify-between text-xs text-muted-foreground">
+              <span>{!validation.success && motion.length > 0 ? 'Use a complete motion so the opponent has something specific to clash with.' : 'Use the exact tournament wording when you have it.'}</span>
+              <span>{motion.length}/1200</span>
+            </div>
+          </div>
+
+          <div className="space-y-2">
+            <Label>Your side</Label>
+            <div className="grid grid-cols-2 gap-2">
+              {(['pro', 'con'] as const).map((value) => (
+                <Button
+                  key={value}
+                  type="button"
+                  variant={side === value ? 'default' : 'outline'}
+                  onClick={() => setSide(value)}
+                  aria-pressed={side === value}
+                >
+                  {value === 'pro' ? 'Pro / Proposition' : 'Con / Opposition'}
+                </Button>
+              ))}
+            </div>
+          </div>
+
+          <div className="space-y-3">
+            <Label>Opponent difficulty</Label>
+            <div className="grid gap-3 md:grid-cols-3">
+              {difficulties.map((item) => (
+                <button
+                  type="button"
+                  key={item.id}
+                  onClick={() => setDifficulty(item.id)}
+                  aria-pressed={difficulty === item.id}
+                  className={cn(
+                    'rounded-lg border p-4 text-left transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                    difficulty === item.id
+                      ? 'border-primary bg-primary/5'
+                      : 'border-border/70 bg-background/40 hover:border-primary/40',
+                  )}
+                >
+                  <item.icon className="mb-3 h-5 w-5 text-primary" />
+                  <div className="font-medium">{item.label}</div>
+                  <div className="mt-1 text-xs leading-relaxed text-muted-foreground">{item.description}</div>
+                </button>
+              ))}
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+
+      <div className="space-y-4">
+        <Card className="border-border/70 bg-card/70">
+          <CardHeader className="pb-3">
+            <CardTitle className="text-base">Round intelligence</CardTitle>
+            <CardDescription>Choose the model independently from Ask.</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <ModelSelector feature="sparring" showLabel />
+          </CardContent>
+        </Card>
+
+        <Card className="border-border/70 bg-card/70">
+          <CardContent className="flex items-start justify-between gap-4 pt-6">
+            <div>
+              <div className="flex items-center gap-2 font-medium">
+                <BookOpenCheck className="h-4 w-4 text-primary" />
+                Use active sources
+              </div>
+              <p className="mt-1 text-xs leading-relaxed text-muted-foreground">
+                {activeSourceCount > 0
+                  ? `${activeSourceCount} active ${activeSourceCount === 1 ? 'source is' : 'sources are'} available as grounding context.`
+                  : 'No active sources are currently selected. The opponent will avoid inventing evidence.'}
+              </p>
+            </div>
+            <Switch checked={useActiveSources} onCheckedChange={setUseActiveSources} aria-label="Use active sources for sparring" />
+          </CardContent>
+        </Card>
+
+        <Button className="w-full" size="lg" disabled={!validation.success || isStarting} onClick={handleStart}>
+          <Swords className="mr-2 h-4 w-4" />
+          Start sparring
+        </Button>
+      </div>
+    </div>
+  );
+}

From 0b468892f5fc79278ce92c3ceb4d34743701d4ac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:26:47 +0200
Subject: [PATCH 07/84] feat: add playable sparring round UI

---
 .../features/sparring/SparringRound.tsx       | 147 ++++++++++++++++++
 1 file changed, 147 insertions(+)
 create mode 100644 src/components/features/sparring/SparringRound.tsx

diff --git a/src/components/features/sparring/SparringRound.tsx b/src/components/features/sparring/SparringRound.tsx
new file mode 100644
index 000000000..98d23ac48
--- /dev/null
+++ b/src/components/features/sparring/SparringRound.tsx
@@ -0,0 +1,147 @@
+import { useMemo, useState } from 'react';
+import { Bot, Flag, Send, UserRound } from 'lucide-react';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Markdown } from '@/components/ui/markdown';
+import { Textarea } from '@/components/ui/textarea';
+import { StreamingIndicator } from '@/components/ui/streaming-indicator';
+import type { SparringSession, SparringTurnPhase } from '@/lib/ai/schemas/sparring';
+
+interface SparringRoundProps {
+  session: SparringSession;
+  isThinking: boolean;
+  pressurePoints: string[];
+  onSubmitSpeech: (content: string, phase: SparringTurnPhase) => Promise<void> | void;
+  onFinish: () => Promise<void> | void;
+}
+
+export function SparringRound({ session, isThinking, pressurePoints, onSubmitSpeech, onFinish }: SparringRoundProps) {
+  const [draft, setDraft] = useState('');
+  const userTurns = session.turns.filter((turn) => turn.role === 'user').length;
+  const aiTurns = session.turns.filter((turn) => turn.role === 'ai').length;
+  const phase: SparringTurnPhase = userTurns === 0 ? 'opening' : 'rebuttal';
+  const canSubmit = draft.trim().length >= 20 && !isThinking && userTurns < 2 && userTurns === aiTurns;
+  const canFinish = userTurns >= 2 && aiTurns >= 2 && !isThinking;
+
+  const roundLabel = useMemo(() => {
+    if (userTurns === 0) return 'Your opening';
+    if (userTurns === 1 && aiTurns === 1) return 'Your rebuttal';
+    if (userTurns >= 2 && aiTurns >= 2) return 'Round complete';
+    return 'Opponent responding';
+  }, [userTurns, aiTurns]);
+
+  const submit = async () => {
+    if (!canSubmit) return;
+    const speech = draft.trim();
+    setDraft('');
+    await onSubmitSpeech(speech, phase);
+  };
+
+  return (
+    <div className="grid gap-6 xl:grid-cols-[minmax(0,1fr)_320px]">
+      <div className="space-y-4">
+        <Card className="border-primary/20 bg-primary/5">
+          <CardContent className="flex flex-col gap-3 pt-6 sm:flex-row sm:items-center sm:justify-between">
+            <div>
+              <div className="flex flex-wrap items-center gap-2">
+                <Badge variant="outline">{session.setup.side === 'pro' ? 'Pro / Proposition' : 'Con / Opposition'}</Badge>
+                <Badge variant="outline" className="capitalize">{session.setup.difficulty}</Badge>
+                <Badge variant="secondary">{Math.min(session.turns.length, 4)}/4 speeches</Badge>
+              </div>
+              <h2 className="mt-3 text-xl font-semibold">{session.setup.motion}</h2>
+            </div>
+            <div className="text-sm font-medium text-primary">{roundLabel}</div>
+          </CardContent>
+        </Card>
+
+        <div className="space-y-3" aria-live="polite">
+          {session.turns.map((turn) => (
+            <Card key={turn.id} className={turn.role === 'user' ? 'ml-auto max-w-[92%] border-primary/30' : 'mr-auto max-w-[92%] border-border/70 bg-card/70'}>
+              <CardHeader className="pb-2">
+                <CardTitle className="flex items-center gap-2 text-sm">
+                  {turn.role === 'user' ? <UserRound className="h-4 w-4 text-primary" /> : <Bot className="h-4 w-4 text-primary" />}
+                  {turn.role === 'user' ? 'You' : 'AI opponent'}
+                  <Badge variant="outline" className="ml-auto capitalize text-[10px]">{turn.phase}</Badge>
+                </CardTitle>
+              </CardHeader>
+              <CardContent>
+                {turn.role === 'ai' ? <Markdown>{turn.content}</Markdown> : <p className="whitespace-pre-wrap text-sm leading-relaxed">{turn.content}</p>}
+              </CardContent>
+            </Card>
+          ))}
+
+          {isThinking && (
+            <Card className="mr-auto max-w-[92%] border-border/70 bg-card/70">
+              <CardContent className="pt-6">
+                <StreamingIndicator messages={[
+                  'Finding the strongest clash...',
+                  'Testing your warrants...',
+                  'Building the opponent response...',
+                ]} />
+              </CardContent>
+            </Card>
+          )}
+        </div>
+
+        {userTurns < 2 ? (
+          <Card className="border-border/70 bg-card/70">
+            <CardHeader className="pb-3">
+              <CardTitle className="text-base">{phase === 'opening' ? 'Deliver your opening' : 'Answer the clash'}</CardTitle>
+            </CardHeader>
+            <CardContent className="space-y-3">
+              <Textarea
+                value={draft}
+                onChange={(event) => setDraft(event.target.value)}
+                disabled={isThinking || userTurns !== aiTurns}
+                placeholder={phase === 'opening'
+                  ? 'Build your case. Give the AI something specific to attack: claim, warrant, impact, and evidence if you have it.'
+                  : 'Do not restart your case. Answer the opponent, repair your warrant, and weigh why your side still wins.'}
+                className="min-h-44 resize-y"
+                maxLength={6000}
+              />
+              <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
+                <span className="text-xs text-muted-foreground">{draft.length}/6000 · Minimum 20 characters</span>
+                <Button onClick={submit} disabled={!canSubmit}>
+                  <Send className="mr-2 h-4 w-4" />
+                  Send {phase}
+                </Button>
+              </div>
+            </CardContent>
+          </Card>
+        ) : (
+          <Button size="lg" onClick={onFinish} disabled={!canFinish} className="w-full sm:w-auto">
+            <Flag className="mr-2 h-4 w-4" />
+            Finish and get scorecard
+          </Button>
+        )}
+      </div>
+
+      <aside className="space-y-4 xl:sticky xl:top-24 xl:self-start">
+        <Card className="border-border/70 bg-card/70">
+          <CardHeader className="pb-3">
+            <CardTitle className="text-base">Round objective</CardTitle>
+          </CardHeader>
+          <CardContent className="space-y-2 text-sm text-muted-foreground">
+            <p><strong className="text-foreground">Opening:</strong> establish a clear warrant chain and impact.</p>
+            <p><strong className="text-foreground">Rebuttal:</strong> answer the opponent's actual offense, then compare worlds.</p>
+            <p><strong className="text-foreground">Scorecard:</strong> uses only the typed transcript. It will not pretend to judge vocal delivery.</p>
+          </CardContent>
+        </Card>
+
+        {pressurePoints.length > 0 && (
+          <Card className="border-destructive/20 bg-destructive/5">
+            <CardHeader className="pb-3">
+              <CardTitle className="text-base">Opponent pressure points</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <ul className="space-y-2 text-sm text-muted-foreground">
+                {pressurePoints.map((point) => <li key={point}>• {point}</li>)}
+              </ul>
+            </CardContent>
+          </Card>
+        )}
+      </aside>
+    </div>
+  );
+}

From be47464d5b0a3321f35c208d4879a71eb23af9fb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:27:16 +0200
Subject: [PATCH 08/84] feat: add evidence-backed sparring scorecard UI

---
 .../features/sparring/SparringScorecard.tsx   | 137 ++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 src/components/features/sparring/SparringScorecard.tsx

diff --git a/src/components/features/sparring/SparringScorecard.tsx b/src/components/features/sparring/SparringScorecard.tsx
new file mode 100644
index 000000000..446babae2
--- /dev/null
+++ b/src/components/features/sparring/SparringScorecard.tsx
@@ -0,0 +1,137 @@
+import { ArrowRight, CheckCircle2, MessageCircle, RefreshCcw, Target, Trophy } from 'lucide-react';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import type { SparringScorecard as SparringScorecardType, SparringSession } from '@/lib/ai/schemas/sparring';
+import { cn } from '@/lib/utils';
+
+interface SparringScorecardProps {
+  session: SparringSession;
+  scorecard: SparringScorecardType;
+  onRematch: () => void;
+  onDiscuss: () => void;
+  onNewRound: () => void;
+}
+
+const categoryLabels: Record<SparringScorecardType['categories'][number]['category'], string> = {
+  'argument-strength': 'Argument strength',
+  'warrant-quality': 'Warrant quality',
+  'impact-analysis': 'Impact analysis',
+  engagement: 'Engagement',
+  'rebuttal-efficiency': 'Rebuttal efficiency',
+  weighing: 'Weighing',
+  'evidence-use': 'Evidence use',
+  strategy: 'Strategy',
+};
+
+function ratingClass(rating: SparringScorecardType['categories'][number]['rating']) {
+  if (rating === 'strong') return 'border-green-500/30 bg-green-500/10 text-green-700 dark:text-green-300';
+  if (rating === 'needs-work') return 'border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-300';
+  return 'border-primary/25 bg-primary/10 text-primary';
+}
+
+export function SparringScorecard({ session, scorecard, onRematch, onDiscuss, onNewRound }: SparringScorecardProps) {
+  const verdictLabel = scorecard.verdict === 'user-edge'
+    ? 'Your side had the edge'
+    : scorecard.verdict === 'ai-edge'
+      ? 'Opponent had the edge'
+      : 'Close round';
+
+  return (
+    <div className="space-y-6">
+      <Card className="overflow-hidden border-primary/25 bg-gradient-to-br from-primary/10 via-card to-card">
+        <CardHeader>
+          <div className="flex flex-col gap-4 sm:flex-row sm:items-start sm:justify-between">
+            <div>
+              <div className="flex items-center gap-2 text-primary">
+                <Trophy className="h-5 w-5" />
+                <span className="text-sm font-semibold uppercase tracking-wide">Round review</span>
+              </div>
+              <CardTitle className="mt-2 text-2xl">{verdictLabel}</CardTitle>
+              <CardDescription className="mt-2 max-w-3xl text-sm leading-relaxed">{scorecard.summary}</CardDescription>
+            </div>
+            <Badge variant="outline" className="w-fit capitalize">{session.setup.difficulty}</Badge>
+          </div>
+        </CardHeader>
+        <CardContent>
+          <div className="rounded-lg border border-primary/20 bg-background/60 p-4">
+            <div className="flex items-start gap-3">
+              <Target className="mt-0.5 h-5 w-5 shrink-0 text-primary" />
+              <div>
+                <div className="font-semibold">Your single biggest improvement</div>
+                <p className="mt-1 text-sm leading-relaxed text-muted-foreground">{scorecard.biggestImprovement}</p>
+              </div>
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+
+      <div className="grid gap-4 md:grid-cols-2">
+        {scorecard.categories.map((item) => (
+          <Card key={item.category} className="border-border/70 bg-card/70">
+            <CardHeader className="pb-3">
+              <div className="flex items-center justify-between gap-3">
+                <CardTitle className="text-base">{categoryLabels[item.category]}</CardTitle>
+                <Badge variant="outline" className={cn('capitalize', ratingClass(item.rating))}>{item.rating.replace('-', ' ')}</Badge>
+              </div>
+            </CardHeader>
+            <CardContent className="space-y-3 text-sm">
+              <div>
+                <div className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">What happened</div>
+                <p className="mt-1 leading-relaxed">{item.evidence}</p>
+              </div>
+              <div>
+                <div className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">Next adjustment</div>
+                <p className="mt-1 leading-relaxed text-muted-foreground">{item.advice}</p>
+              </div>
+            </CardContent>
+          </Card>
+        ))}
+      </div>
+
+      <div className="grid gap-4 lg:grid-cols-3">
+        <Card className="border-border/70 bg-card/70">
+          <CardHeader className="pb-3"><CardTitle className="text-base">What worked</CardTitle></CardHeader>
+          <CardContent>
+            <ul className="space-y-2 text-sm text-muted-foreground">
+              {scorecard.strengths.length > 0 ? scorecard.strengths.map((item) => (
+                <li key={item} className="flex gap-2"><CheckCircle2 className="mt-0.5 h-4 w-4 shrink-0 text-primary" /><span>{item}</span></li>
+              )) : <li>No specific strength was identified strongly enough to list.</li>}
+            </ul>
+          </CardContent>
+        </Card>
+
+        <Card className="border-border/70 bg-card/70">
+          <CardHeader className="pb-3"><CardTitle className="text-base">Missed opportunities</CardTitle></CardHeader>
+          <CardContent>
+            <ul className="space-y-2 text-sm text-muted-foreground">
+              {scorecard.missedArguments.length > 0 ? scorecard.missedArguments.map((item) => <li key={item}>• {item}</li>) : <li>No major missed argument was identified.</li>}
+            </ul>
+          </CardContent>
+        </Card>
+
+        <Card className="border-primary/20 bg-primary/5">
+          <CardHeader className="pb-3"><CardTitle className="text-base">Next drill</CardTitle></CardHeader>
+          <CardContent>
+            <p className="text-sm leading-relaxed text-muted-foreground">{scorecard.nextDrill}</p>
+          </CardContent>
+        </Card>
+      </div>
+
+      <div className="flex flex-col gap-2 sm:flex-row sm:flex-wrap">
+        <Button onClick={onRematch}>
+          <RefreshCcw className="mr-2 h-4 w-4" />
+          Rematch this motion
+        </Button>
+        <Button variant="outline" onClick={onDiscuss}>
+          <MessageCircle className="mr-2 h-4 w-4" />
+          Discuss with Ask
+        </Button>
+        <Button variant="ghost" onClick={onNewRound}>
+          New motion
+          <ArrowRight className="ml-2 h-4 w-4" />
+        </Button>
+      </div>
+    </div>
+  );
+}

From 1f1646056ae8d86b31607e1e361d1d0daecc3ebe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:28:00 +0200
Subject: [PATCH 09/84] feat: wire complete sparring training loop

---
 src/pages/SparringPage.tsx | 259 +++++++++++++++++++++++++++++++++++++
 1 file changed, 259 insertions(+)
 create mode 100644 src/pages/SparringPage.tsx

diff --git a/src/pages/SparringPage.tsx b/src/pages/SparringPage.tsx
new file mode 100644
index 000000000..838cb66e3
--- /dev/null
+++ b/src/pages/SparringPage.tsx
@@ -0,0 +1,259 @@
+import { useMemo, useState } from 'react';
+import { History, Swords } from 'lucide-react';
+import { useNavigate } from 'react-router-dom';
+import { SparringSetup } from '@/components/features/sparring/SparringSetup';
+import { SparringRound } from '@/components/features/sparring/SparringRound';
+import { SparringScorecard } from '@/components/features/sparring/SparringScorecard';
+import { LimitReachedModal, ModelRestrictedModal, PricingModal } from '@/components/features/subscription';
+import { AnimatedSection } from '@/components/ui/animated-section';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { StreamingIndicator } from '@/components/ui/streaming-indicator';
+import { askChat } from '@/lib/ai/client';
+import { requestSparringOpponent, requestSparringScorecard } from '@/lib/ai/sparring-client';
+import type { SparringSetup as SparringSetupType, SparringTurnPhase } from '@/lib/ai/schemas/sparring';
+import { getUserFacingAIError } from '@/lib/ai/error-display';
+import { captureProductEvent } from '@/lib/observability';
+import { useSettingsStore } from '@/lib/stores/settings-store';
+import { getSparringSession, useSparringStore } from '@/lib/stores/sparring-store';
+import { useSessionStore } from '@/lib/stores/session-store';
+import { useSubscriptionError } from '@/hooks/use-subscription-error';
+import { useToast } from '@/hooks/use-toast';
+
+function transcriptText(turns: ReturnType<typeof getSparringSession> extends infer _T ? Array<{ role: 'user' | 'ai'; phase: string; content: string }> : never) {
+  return turns.map((turn, index) => `${index + 1}. ${turn.role === 'user' ? 'You' : 'AI opponent'} (${turn.phase}): ${turn.content}`).join('\n\n');
+}
+
+export default function SparringPage() {
+  const navigate = useNavigate();
+  const { toast } = useToast();
+  const subError = useSubscriptionError();
+  const config = useSettingsStore((state) => state.getFeatureConfig('sparring'));
+  const askConfig = useSettingsStore((state) => state.getFeatureConfig('ask'));
+  const sessions = useSparringStore((state) => state.sessions);
+  const activeSessionId = useSparringStore((state) => state.activeSessionId);
+  const startSession = useSparringStore((state) => state.startSession);
+  const addTurn = useSparringStore((state) => state.addTurn);
+  const completeSession = useSparringStore((state) => state.completeSession);
+  const setActiveSession = useSparringStore((state) => state.setActiveSession);
+  const { addAskMessage, setAskLoading, askMessages } = useSessionStore();
+  const [isThinking, setIsThinking] = useState(false);
+  const [isScoring, setIsScoring] = useState(false);
+  const [pressurePoints, setPressurePoints] = useState<string[]>([]);
+
+  const session = useMemo(
+    () => sessions.find((item) => item.id === activeSessionId) ?? null,
+    [sessions, activeSessionId],
+  );
+  const recentCompleted = sessions.filter((item) => item.status === 'complete').slice(0, 5);
+
+  const handleAIError = (error: unknown, title: string) => {
+    console.error(title, error);
+    if (!subError.handleSubscriptionError(error)) {
+      toast({ title, description: getUserFacingAIError(error), variant: 'destructive' });
+    }
+  };
+
+  const handleStart = (setup: SparringSetupType) => {
+    const created = startSession(setup);
+    setPressurePoints([]);
+    captureProductEvent('sparring_started', {
+      difficulty: setup.difficulty,
+      side: setup.side,
+      active_sources: setup.useActiveSources,
+    });
+    setActiveSession(created.id);
+  };
+
+  const handleSubmitSpeech = async (content: string, phase: SparringTurnPhase) => {
+    if (!session || isThinking) return;
+    addTurn(session.id, { role: 'user', phase, content });
+    captureProductEvent(phase === 'opening' ? 'sparring_opening_submitted' : 'sparring_turn_completed', {
+      phase,
+      speech_length: content.length,
+      difficulty: session.setup.difficulty,
+    });
+
+    const updated = getSparringSession(session.id);
+    if (!updated) return;
+
+    setIsThinking(true);
+    try {
+      const opponent = await requestSparringOpponent(updated, content, config);
+      addTurn(session.id, { role: 'ai', phase, content: opponent.speech });
+      setPressurePoints(opponent.pressurePoints);
+      captureProductEvent('sparring_turn_completed', {
+        phase,
+        speaker: 'ai',
+        pressure_points: opponent.pressurePoints.length,
+      });
+    } catch (error) {
+      handleAIError(error, 'Opponent response failed');
+    } finally {
+      setIsThinking(false);
+    }
+  };
+
+  const handleFinish = async () => {
+    if (!session || isScoring) return;
+    const current = getSparringSession(session.id);
+    if (!current || current.turns.filter((turn) => turn.role === 'user').length < 2 || current.turns.filter((turn) => turn.role === 'ai').length < 2) return;
+
+    setIsScoring(true);
+    captureProductEvent('sparring_completed', {
+      difficulty: current.setup.difficulty,
+      turns: current.turns.length,
+    });
+    try {
+      const scorecard = await requestSparringScorecard(current, config);
+      completeSession(current.id, scorecard);
+      captureProductEvent('sparring_scorecard_viewed', {
+        verdict: scorecard.verdict,
+        difficulty: current.setup.difficulty,
+      });
+    } catch (error) {
+      handleAIError(error, 'Scorecard failed');
+    } finally {
+      setIsScoring(false);
+    }
+  };
+
+  const handleRematch = () => {
+    if (!session) return;
+    const next = startSession(session.setup);
+    setPressurePoints([]);
+    captureProductEvent('sparring_restarted', { same_motion: true, difficulty: session.setup.difficulty });
+    setActiveSession(next.id);
+  };
+
+  const handleDiscuss = async () => {
+    if (!session?.scorecard) return;
+    const prompt = `I just finished a DebateLab sparring round and want to improve it.\n\nMotion: ${session.setup.motion}\nMy side: ${session.setup.side}\nVerdict: ${session.scorecard.verdict}\nBiggest improvement: ${session.scorecard.biggestImprovement}\nNext drill: ${session.scorecard.nextDrill}\n\nTranscript:\n${transcriptText(session.turns)}\n\nHelp me turn this feedback into a concrete improvement plan. Focus on the actual transcript.`;
+
+    addAskMessage({ role: 'user', content: prompt });
+    navigate('/app/ask');
+    captureProductEvent('sparring_feedback_action_used', { action: 'discuss_in_ask' });
+    setAskLoading(true);
+    try {
+      const history = [...askMessages, { role: 'user' as const, content: prompt }].map((message) => ({
+        role: message.role as 'user' | 'assistant',
+        content: message.content,
+      }));
+      const result = await askChat(prompt, history, 'general', askConfig);
+      addAskMessage({ role: 'assistant', content: result.response, output: result });
+    } catch (error) {
+      if (!subError.handleSubscriptionError(error)) {
+        toast({ title: 'Coach follow-up failed', description: getUserFacingAIError(error), variant: 'destructive' });
+      }
+    } finally {
+      setAskLoading(false);
+    }
+  };
+
+  const handleNewRound = () => {
+    setPressurePoints([]);
+    setActiveSession(null);
+  };
+
+  return (
+    <div className="container px-4 py-8">
+      <div className="mx-auto max-w-6xl">
+        <AnimatedSection className="mb-8">
+          <div className="flex items-center gap-3">
+            <div className="flex h-11 w-11 items-center justify-center rounded-xl bg-primary/10 text-primary">
+              <Swords className="h-6 w-6" />
+            </div>
+            <div>
+              <h1 className="text-3xl font-bold tracking-tight">Sparring</h1>
+              <p className="mt-1 text-muted-foreground">Research. Build. Practice. Diagnose. Improve.</p>
+            </div>
+          </div>
+        </AnimatedSection>
+
+        {isScoring && session ? (
+          <AnimatedSection>
+            <Card className="min-h-[420px] border-primary/20 bg-primary/5">
+              <CardContent className="flex min-h-[420px] items-center justify-center pt-6">
+                <StreamingIndicator messages={[
+                  'Replaying the clash...',
+                  'Checking warrants against the transcript...',
+                  'Comparing impacts and weighing...',
+                  'Building your next drill...',
+                ]} />
+              </CardContent>
+            </Card>
+          </AnimatedSection>
+        ) : session?.status === 'complete' && session.scorecard ? (
+          <AnimatedSection>
+            <SparringScorecard
+              session={session}
+              scorecard={session.scorecard}
+              onRematch={handleRematch}
+              onDiscuss={handleDiscuss}
+              onNewRound={handleNewRound}
+            />
+          </AnimatedSection>
+        ) : session ? (
+          <AnimatedSection>
+            <SparringRound
+              session={session}
+              isThinking={isThinking}
+              pressurePoints={pressurePoints}
+              onSubmitSpeech={handleSubmitSpeech}
+              onFinish={handleFinish}
+            />
+          </AnimatedSection>
+        ) : (
+          <>
+            <AnimatedSection>
+              <SparringSetup onStart={handleStart} />
+            </AnimatedSection>
+
+            {recentCompleted.length > 0 && (
+              <AnimatedSection delay={100} className="mt-8">
+                <Card className="border-border/70 bg-card/60">
+                  <CardHeader className="pb-3">
+                    <CardTitle className="flex items-center gap-2 text-base"><History className="h-4 w-4 text-primary" />Recent sparring rounds</CardTitle>
+                  </CardHeader>
+                  <CardContent className="space-y-2">
+                    {recentCompleted.map((item) => (
+                      <button
+                        type="button"
+                        key={item.id}
+                        onClick={() => setActiveSession(item.id)}
+                        className="flex w-full items-center justify-between gap-4 rounded-lg border border-border/60 px-4 py-3 text-left transition-colors hover:border-primary/30 hover:bg-accent/40"
+                      >
+                        <div className="min-w-0">
+                          <div className="truncate text-sm font-medium">{item.setup.motion}</div>
+                          <div className="mt-1 text-xs text-muted-foreground">{new Date(item.createdAt).toLocaleString()}</div>
+                        </div>
+                        <Badge variant="outline" className="shrink-0 capitalize">{item.scorecard?.verdict.replace('-', ' ')}</Badge>
+                      </button>
+                    ))}
+                    <Button variant="ghost" size="sm" onClick={() => navigate('/app/history')}>Open full history</Button>
+                  </CardContent>
+                </Card>
+              </AnimatedSection>
+            )}
+          </>
+        )}
+      </div>
+
+      <LimitReachedModal
+        open={subError.limitModalOpen}
+        onOpenChange={subError.setLimitModalOpen}
+        variant={subError.limitModalVariant}
+        limit={subError.limitModalLimit}
+        current={subError.limitModalCurrent}
+        onUpgrade={() => { subError.setLimitModalOpen(false); subError.setPricingModalOpen(true); }}
+      />
+      <ModelRestrictedModal
+        open={subError.modelModalOpen}
+        onOpenChange={subError.setModelModalOpen}
+        onUpgrade={() => { subError.setModelModalOpen(false); subError.setPricingModalOpen(true); }}
+      />
+      <PricingModal open={subError.pricingModalOpen} onOpenChange={subError.setPricingModalOpen} />
+    </div>
+  );
+}

From ad26d942ebd59f8babe77db36432cef6e8560388 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:28:26 +0200
Subject: [PATCH 10/84] feat: route sparring mode

---
 src/App.tsx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/App.tsx b/src/App.tsx
index f68db8b2e..6cfff11f3 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -25,6 +25,7 @@ const AttackPage = lazy(() => import("./pages/AttackPage"));
 const BrainstormPage = lazy(() => import("./pages/BrainstormPage"));
 const FactoidsPage = lazy(() => import("./pages/FactoidsPage"));
 const AskPage = lazy(() => import("./pages/AskPage"));
+const SparringPage = lazy(() => import("./pages/SparringPage"));
 const SettingsPage = lazy(() => import("./pages/SettingsPage"));
 const HistoryPage = lazy(() => import("./pages/HistoryPage"));
 const LibraryPage = lazy(() => import("./pages/LibraryPage"));
@@ -118,6 +119,7 @@ function AnimatedRoutes() {
             <Route path="/app/brainstorm" element={<BrainstormPage />} />
             <Route path="/app/factoids" element={<FactoidsPage />} />
             <Route path="/app/ask" element={<AskPage />} />
+            <Route path="/app/sparring" element={<SparringPage />} />
             <Route path="/app/history" element={<HistoryPage />} />
             <Route path="/app/library" element={<LibraryPage />} />
             <Route path="/app/timer" element={<TimerPage />} />

From a81a6ef053008179c3a965784befa1dfd104ec34 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:28:48 +0200
Subject: [PATCH 11/84] feat: add sparring to app navigation

---
 src/components/layout/AppLayout.tsx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/components/layout/AppLayout.tsx b/src/components/layout/AppLayout.tsx
index 55c85a3d6..4527b5392 100644
--- a/src/components/layout/AppLayout.tsx
+++ b/src/components/layout/AppLayout.tsx
@@ -15,7 +15,8 @@ import {
   Clock,
   Timer,
   Database,
-  GitBranch
+  GitBranch,
+  Dumbbell,
 } from 'lucide-react';
 import { NavLink } from '@/components/NavLink';
 import { Button } from '@/components/ui/button';
@@ -30,6 +31,7 @@ const navItems = [
   { path: '/app/brainstorm', key: 'brainstorm', icon: Lightbulb },
   { path: '/app/factoids', key: 'factoids', icon: BookOpen },
   { path: '/app/ask', key: 'ask', icon: MessageCircle },
+  { path: '/app/sparring', key: 'sparring', icon: Dumbbell },
   { path: '/app/library', key: 'library', icon: Database },
   { path: '/app/timer', key: 'timer', icon: Timer },
   { path: '/app/flowchart', key: 'flowchart', icon: GitBranch },

From a2f7c21c2d21223f1db116b97d7d529ab64886ee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:29:03 +0200
Subject: [PATCH 12/84] feat: surface sparring from app home

---
 src/pages/HomePage.tsx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/pages/HomePage.tsx b/src/pages/HomePage.tsx
index b045be146..b82055036 100644
--- a/src/pages/HomePage.tsx
+++ b/src/pages/HomePage.tsx
@@ -10,7 +10,8 @@ import {
   Timer,
   GitBranch,
   Clock,
-  ArrowRight
+  ArrowRight,
+  Dumbbell,
 } from 'lucide-react';
 import { Card, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 import { cn } from '@/lib/utils';
@@ -21,6 +22,7 @@ const modeKeys = [
   { key: 'brainstorm', icon: Lightbulb, href: '/app/brainstorm' },
   { key: 'factoids', icon: BookOpen, href: '/app/factoids' },
   { key: 'ask', icon: MessageCircle, href: '/app/ask' },
+  { key: 'sparring', icon: Dumbbell, href: '/app/sparring' },
   { key: 'library', icon: Database, href: '/app/library' },
   { key: 'timer', icon: Timer, href: '/app/timer' },
   { key: 'flowchart', icon: GitBranch, href: '/app/flowchart' },

From b296e3a1dd34aa69241f9423a9e87e9348f6b080 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:30:09 +0200
Subject: [PATCH 13/84] feat: integrate sparring rounds into history

---
 src/pages/HistoryPage.tsx | 73 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 71 insertions(+), 2 deletions(-)

diff --git a/src/pages/HistoryPage.tsx b/src/pages/HistoryPage.tsx
index 76507e224..faa3bdd19 100644
--- a/src/pages/HistoryPage.tsx
+++ b/src/pages/HistoryPage.tsx
@@ -1,10 +1,11 @@
 import { useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSessionStore } from '@/lib/stores/session-store';
+import { useSparringStore } from '@/lib/stores/sparring-store';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import { Button } from '@/components/ui/button';
-import { Trash2, Eye, MessageCircle, FileText, Zap, Brain, BookOpen } from 'lucide-react';
+import { Trash2, Eye, MessageCircle, FileText, Zap, Brain, BookOpen, Dumbbell } from 'lucide-react';
 import { useNavigate } from 'react-router-dom';
 import { Badge } from '@/components/ui/badge';
 import { ScrollArea } from '@/components/ui/scroll-area';
@@ -26,6 +27,9 @@ export default function HistoryPage() {
   const { t } = useTranslation();
   const navigate = useNavigate();
   const store = useSessionStore();
+  const sparringSessions = useSparringStore((state) => state.sessions);
+  const setActiveSparringSession = useSparringStore((state) => state.setActiveSession);
+  const deleteSparringSession = useSparringStore((state) => state.deleteSession);
   const { toast } = useToast();
   const [caseToDelete, setCaseToDelete] = useState<{ id: string; title: string } | null>(null);
 
@@ -54,6 +58,11 @@ export default function HistoryPage() {
     navigate('/app/factoids');
   };
 
+  const handleLoadSparring = (id: string) => {
+    setActiveSparringSession(id);
+    navigate('/app/sparring');
+  };
+
   const confirmDeleteCase = () => {
     if (!caseToDelete) return;
     void store.deleteSavedCase(caseToDelete.id)
@@ -77,9 +86,10 @@ export default function HistoryPage() {
         </div>
 
         <Tabs defaultValue="cases" className="space-y-6">
-          <TabsList>
+          <TabsList className="h-auto flex-wrap justify-start">
             <TabsTrigger value="cases" className="gap-2"><FileText className="h-4 w-4" /> {t('historyPage.tabCases')}</TabsTrigger>
             <TabsTrigger value="chats" className="gap-2"><MessageCircle className="h-4 w-4" /> {t('historyPage.tabChats')}</TabsTrigger>
+            <TabsTrigger value="sparring" className="gap-2"><Dumbbell className="h-4 w-4" /> {t('historyPage.tabSparring', 'Sparring')}</TabsTrigger>
             <TabsTrigger value="attacks" className="gap-2"><Zap className="h-4 w-4" /> {t('historyPage.tabAttacks')}</TabsTrigger>
             <TabsTrigger value="brainstorms" className="gap-2"><Brain className="h-4 w-4" /> {t('historyPage.tabBrainstorms')}</TabsTrigger>
             <TabsTrigger value="factoids" className="gap-2"><BookOpen className="h-4 w-4" /> {t('historyPage.tabFactoids')}</TabsTrigger>
@@ -169,6 +179,62 @@ export default function HistoryPage() {
             </Card>
           </TabsContent>
 
+          <TabsContent value="sparring">
+            <Card>
+              <CardHeader>
+                <CardTitle>{t('historyPage.sparringTitle', 'Sparring rounds')}</CardTitle>
+                <CardDescription>{t('historyPage.sparringDesc', 'Completed and in-progress practice rounds are kept locally on this device.')}</CardDescription>
+              </CardHeader>
+              <CardContent>
+                {sparringSessions.length === 0 ? (
+                  <EmptyState
+                    icon={Dumbbell}
+                    title={t('historyPage.emptySparring', 'No sparring rounds yet')}
+                    description={t('historyPage.emptySparringDesc', 'Practice against the AI opponent and your scorecards will appear here.')}
+                    actionLabel={t('historyPage.startSparring', 'Start sparring')}
+                    onAction={() => navigate('/app/sparring')}
+                  />
+                ) : (
+                  <ScrollArea className="h-[500px] pr-4">
+                    <div className="space-y-4">
+                      {sparringSessions.map((item) => (
+                        <div key={item.id} className="flex flex-col gap-3 p-4 border rounded-lg bg-card hover:bg-accent/5 transition-colors sm:flex-row sm:items-center sm:justify-between">
+                          <div className="min-w-0 space-y-1">
+                            <h4 className="truncate font-semibold">{item.setup.motion}</h4>
+                            <div className="flex flex-wrap gap-2 text-xs text-muted-foreground">
+                              <Badge variant="outline" className="uppercase">{item.setup.side}</Badge>
+                              <Badge variant="outline" className="capitalize">{item.setup.difficulty}</Badge>
+                              <Badge variant={item.status === 'complete' ? 'secondary' : 'outline'} className="capitalize">{item.status}</Badge>
+                              {item.scorecard && <Badge variant="outline" className="capitalize">{item.scorecard.verdict.replace('-', ' ')}</Badge>}
+                              <span>{formatEuropeanDateTime(item.createdAt)}</span>
+                            </div>
+                          </div>
+                          <div className="flex gap-2">
+                            <Button variant="outline" size="sm" onClick={() => handleLoadSparring(item.id)}>
+                              <Eye className="h-4 w-4 mr-2" /> {item.status === 'complete' ? t('historyPage.load') : t('historyPage.resume')}
+                            </Button>
+                            <Button
+                              variant="ghost"
+                              size="icon"
+                              className="text-destructive"
+                              onClick={() => {
+                                deleteSparringSession(item.id);
+                                toast({ title: t('common.deleted', 'Deleted'), description: t('historyPage.sparringDeleted', 'Sparring round deleted from this device.') });
+                              }}
+                              aria-label={`Delete sparring round: ${item.setup.motion}`}
+                            >
+                              <Trash2 className="h-4 w-4" />
+                            </Button>
+                          </div>
+                        </div>
+                      ))}
+                    </div>
+                  </ScrollArea>
+                )}
+              </CardContent>
+            </Card>
+          </TabsContent>
+
           <TabsContent value="attacks">
             <Card>
               <CardHeader>
@@ -200,6 +266,7 @@ export default function HistoryPage() {
               </CardContent>
             </Card>
           </TabsContent>
+
           <TabsContent value="brainstorms">
             <Card>
               <CardHeader>
@@ -231,6 +298,7 @@ export default function HistoryPage() {
               </CardContent>
             </Card>
           </TabsContent>
+
           <TabsContent value="factoids">
             <Card>
               <CardHeader>
@@ -263,6 +331,7 @@ export default function HistoryPage() {
             </Card>
           </TabsContent>
         </Tabs>
+
         <AlertDialog open={Boolean(caseToDelete)} onOpenChange={(open) => !open && setCaseToDelete(null)}>
           <AlertDialogContent>
             <AlertDialogHeader>

From e688cced001d6971f7273ddfad079dd4da4b4d96 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:30:33 +0200
Subject: [PATCH 14/84] feat: add sparring transcript exports

---
 src/lib/sparring-export.ts | 118 +++++++++++++++++++++++++++++++++++++
 1 file changed, 118 insertions(+)
 create mode 100644 src/lib/sparring-export.ts

diff --git a/src/lib/sparring-export.ts b/src/lib/sparring-export.ts
new file mode 100644
index 000000000..88375da10
--- /dev/null
+++ b/src/lib/sparring-export.ts
@@ -0,0 +1,118 @@
+import type { SparringSession } from '@/lib/ai/schemas/sparring';
+
+function filenameBase(session: SparringSession) {
+  const safe = session.setup.motion
+    .replace(/[^a-z0-9\s-]/gi, '')
+    .trim()
+    .replace(/\s+/g, '-')
+    .slice(0, 60) || 'sparring-round';
+  return `DebateLab-Sparring-${safe}`;
+}
+
+function transcriptLines(session: SparringSession) {
+  return session.turns.flatMap((turn, index) => [
+    `${index + 1}. ${turn.role === 'user' ? 'You' : 'AI opponent'} — ${turn.phase}`,
+    turn.content,
+    '',
+  ]);
+}
+
+export async function exportSparringToDocx(session: SparringSession): Promise<boolean> {
+  try {
+    const { Document, Packer, Paragraph, TextRun, HeadingLevel } = await import('docx');
+    const { saveAs } = await import('file-saver');
+
+    const scorecard = session.scorecard;
+    const children = [
+      new Paragraph({ text: 'DebateLab Sparring Round', heading: HeadingLevel.TITLE }),
+      new Paragraph({ children: [new TextRun({ text: 'Motion: ', bold: true }), new TextRun(session.setup.motion)] }),
+      new Paragraph({ children: [new TextRun({ text: 'Side: ', bold: true }), new TextRun(session.setup.side.toUpperCase())] }),
+      new Paragraph({ children: [new TextRun({ text: 'Difficulty: ', bold: true }), new TextRun(session.setup.difficulty)] }),
+      new Paragraph({ text: 'Transcript', heading: HeadingLevel.HEADING_1 }),
+      ...session.turns.flatMap((turn, index) => [
+        new Paragraph({
+          children: [new TextRun({ text: `${index + 1}. ${turn.role === 'user' ? 'You' : 'AI opponent'} — ${turn.phase}`, bold: true })],
+          spacing: { before: 180, after: 80 },
+        }),
+        new Paragraph({ text: turn.content, spacing: { after: 160 } }),
+      ]),
+      ...(scorecard ? [
+        new Paragraph({ text: 'Scorecard', heading: HeadingLevel.HEADING_1 }),
+        new Paragraph({ children: [new TextRun({ text: 'Verdict: ', bold: true }), new TextRun(scorecard.verdict.replace('-', ' '))] }),
+        new Paragraph({ text: scorecard.summary, spacing: { after: 160 } }),
+        new Paragraph({ children: [new TextRun({ text: 'Biggest improvement: ', bold: true }), new TextRun(scorecard.biggestImprovement)] }),
+        new Paragraph({ children: [new TextRun({ text: 'Next drill: ', bold: true }), new TextRun(scorecard.nextDrill)], spacing: { after: 180 } }),
+        ...scorecard.categories.flatMap((category) => [
+          new Paragraph({
+            children: [new TextRun({ text: `${category.category.replace(/-/g, ' ')} — ${category.rating.replace('-', ' ')}`, bold: true })],
+            spacing: { before: 140, after: 60 },
+          }),
+          new Paragraph({ children: [new TextRun({ text: 'Evidence: ', italics: true }), new TextRun(category.evidence)] }),
+          new Paragraph({ children: [new TextRun({ text: 'Adjustment: ', italics: true }), new TextRun(category.advice)] }),
+        ]),
+      ] : []),
+    ];
+
+    const doc = new Document({ sections: [{ children }] });
+    const blob = await Packer.toBlob(doc);
+    saveAs(blob, `${filenameBase(session)}.docx`);
+    return true;
+  } catch (error) {
+    console.error('[SparringExport] DOCX export failed', error);
+    return false;
+  }
+}
+
+export async function exportSparringToPdf(session: SparringSession): Promise<boolean> {
+  try {
+    const { jsPDF } = await import('jspdf');
+    const doc = new jsPDF({ unit: 'pt', format: 'a4' });
+    const margin = 48;
+    const pageWidth = doc.internal.pageSize.getWidth();
+    const pageHeight = doc.internal.pageSize.getHeight();
+    const maxWidth = pageWidth - margin * 2;
+    let y = margin;
+
+    const addText = (text: string, size = 10, gap = 8, bold = false) => {
+      doc.setFontSize(size);
+      doc.setFont('helvetica', bold ? 'bold' : 'normal');
+      const lines = doc.splitTextToSize(text, maxWidth) as string[];
+      const lineHeight = size * 1.35;
+      for (const line of lines) {
+        if (y + lineHeight > pageHeight - margin) {
+          doc.addPage();
+          y = margin;
+        }
+        doc.text(line, margin, y);
+        y += lineHeight;
+      }
+      y += gap;
+    };
+
+    addText('DebateLab Sparring Round', 18, 12, true);
+    addText(`Motion: ${session.setup.motion}`, 11, 6, true);
+    addText(`Side: ${session.setup.side.toUpperCase()}    Difficulty: ${session.setup.difficulty}`, 10, 14);
+    addText('Transcript', 14, 8, true);
+    transcriptLines(session).forEach((line) => addText(line || ' ', 10, line ? 5 : 3, /^\d+\./.test(line)));
+
+    if (session.scorecard) {
+      const scorecard = session.scorecard;
+      addText('Scorecard', 14, 8, true);
+      addText(`Verdict: ${scorecard.verdict.replace('-', ' ')}`, 11, 5, true);
+      addText(scorecard.summary, 10, 8);
+      addText(`Biggest improvement: ${scorecard.biggestImprovement}`, 10, 8, true);
+      for (const category of scorecard.categories) {
+        addText(`${category.category.replace(/-/g, ' ')} — ${category.rating.replace('-', ' ')}`, 10, 4, true);
+        addText(`Evidence: ${category.evidence}`, 9, 3);
+        addText(`Adjustment: ${category.advice}`, 9, 7);
+      }
+      addText(`Next drill: ${scorecard.nextDrill}`, 10, 6, true);
+    }
+
+    doc.save(`${filenameBase(session)}.pdf`);
+    return true;
+  } catch (error) {
+    console.error('[SparringExport] PDF export failed', error);
+    return false;
+  }
+}

From d2d900d5763a9e30f32b0ddabcb59a8c9e275def Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:30:59 +0200
Subject: [PATCH 15/84] feat: add sparring Word and PDF actions

---
 .../features/sparring/SparringScorecard.tsx        | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/src/components/features/sparring/SparringScorecard.tsx b/src/components/features/sparring/SparringScorecard.tsx
index 446babae2..278df0cfd 100644
--- a/src/components/features/sparring/SparringScorecard.tsx
+++ b/src/components/features/sparring/SparringScorecard.tsx
@@ -1,4 +1,4 @@
-import { ArrowRight, CheckCircle2, MessageCircle, RefreshCcw, Target, Trophy } from 'lucide-react';
+import { ArrowRight, CheckCircle2, FileDown, FileText, MessageCircle, RefreshCcw, Target, Trophy } from 'lucide-react';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
@@ -11,6 +11,8 @@ interface SparringScorecardProps {
   onRematch: () => void;
   onDiscuss: () => void;
   onNewRound: () => void;
+  onExportDocx: () => void;
+  onExportPdf: () => void;
 }
 
 const categoryLabels: Record<SparringScorecardType['categories'][number]['category'], string> = {
@@ -30,7 +32,7 @@ function ratingClass(rating: SparringScorecardType['categories'][number]['rating
   return 'border-primary/25 bg-primary/10 text-primary';
 }
 
-export function SparringScorecard({ session, scorecard, onRematch, onDiscuss, onNewRound }: SparringScorecardProps) {
+export function SparringScorecard({ session, scorecard, onRematch, onDiscuss, onNewRound, onExportDocx, onExportPdf }: SparringScorecardProps) {
   const verdictLabel = scorecard.verdict === 'user-edge'
     ? 'Your side had the edge'
     : scorecard.verdict === 'ai-edge'
@@ -127,6 +129,14 @@ export function SparringScorecard({ session, scorecard, onRematch, onDiscuss, on
           <MessageCircle className="mr-2 h-4 w-4" />
           Discuss with Ask
         </Button>
+        <Button variant="outline" onClick={onExportDocx}>
+          <FileText className="mr-2 h-4 w-4" />
+          Export Word
+        </Button>
+        <Button variant="outline" onClick={onExportPdf}>
+          <FileDown className="mr-2 h-4 w-4" />
+          Export PDF
+        </Button>
         <Button variant="ghost" onClick={onNewRound}>
           New motion
           <ArrowRight className="ml-2 h-4 w-4" />

From f039e5989689facd6d8085159250d2dfc6d41428 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:31:35 +0200
Subject: [PATCH 16/84] feat: export and discuss sparring feedback

---
 src/pages/SparringPage.tsx | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/src/pages/SparringPage.tsx b/src/pages/SparringPage.tsx
index 838cb66e3..a56504153 100644
--- a/src/pages/SparringPage.tsx
+++ b/src/pages/SparringPage.tsx
@@ -12,16 +12,17 @@ import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { StreamingIndicator } from '@/components/ui/streaming-indicator';
 import { askChat } from '@/lib/ai/client';
 import { requestSparringOpponent, requestSparringScorecard } from '@/lib/ai/sparring-client';
-import type { SparringSetup as SparringSetupType, SparringTurnPhase } from '@/lib/ai/schemas/sparring';
+import type { SparringSetup as SparringSetupType, SparringTurn, SparringTurnPhase } from '@/lib/ai/schemas/sparring';
 import { getUserFacingAIError } from '@/lib/ai/error-display';
 import { captureProductEvent } from '@/lib/observability';
+import { exportSparringToDocx, exportSparringToPdf } from '@/lib/sparring-export';
 import { useSettingsStore } from '@/lib/stores/settings-store';
 import { getSparringSession, useSparringStore } from '@/lib/stores/sparring-store';
 import { useSessionStore } from '@/lib/stores/session-store';
 import { useSubscriptionError } from '@/hooks/use-subscription-error';
 import { useToast } from '@/hooks/use-toast';
 
-function transcriptText(turns: ReturnType<typeof getSparringSession> extends infer _T ? Array<{ role: 'user' | 'ai'; phase: string; content: string }> : never) {
+function transcriptText(turns: SparringTurn[]) {
   return turns.map((turn, index) => `${index + 1}. ${turn.role === 'user' ? 'You' : 'AI opponent'} (${turn.phase}): ${turn.content}`).join('\n\n');
 }
 
@@ -71,6 +72,7 @@ export default function SparringPage() {
     addTurn(session.id, { role: 'user', phase, content });
     captureProductEvent(phase === 'opening' ? 'sparring_opening_submitted' : 'sparring_turn_completed', {
       phase,
+      speaker: 'user',
       speech_length: content.length,
       difficulty: session.setup.difficulty,
     });
@@ -151,6 +153,28 @@ export default function SparringPage() {
     }
   };
 
+  const handleExportDocx = async () => {
+    if (!session) return;
+    const ok = await exportSparringToDocx(session);
+    captureProductEvent('sparring_feedback_action_used', { action: 'export_docx', success: ok });
+    toast({
+      title: ok ? 'Word export ready' : 'Word export failed',
+      description: ok ? 'The round transcript and scorecard were exported.' : 'Could not create the Word document.',
+      variant: ok ? 'success' : 'destructive',
+    });
+  };
+
+  const handleExportPdf = async () => {
+    if (!session) return;
+    const ok = await exportSparringToPdf(session);
+    captureProductEvent('sparring_feedback_action_used', { action: 'export_pdf', success: ok });
+    toast({
+      title: ok ? 'PDF export ready' : 'PDF export failed',
+      description: ok ? 'The round transcript and scorecard were exported.' : 'Could not create the PDF.',
+      variant: ok ? 'success' : 'destructive',
+    });
+  };
+
   const handleNewRound = () => {
     setPressurePoints([]);
     setActiveSession(null);
@@ -192,6 +216,8 @@ export default function SparringPage() {
               onRematch={handleRematch}
               onDiscuss={handleDiscuss}
               onNewRound={handleNewRound}
+              onExportDocx={handleExportDocx}
+              onExportPdf={handleExportPdf}
             />
           </AnimatedSection>
         ) : session ? (

From 2cdd2732caffb9336dde2458220eddd096f14edf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:32:03 +0200
Subject: [PATCH 17/84] fix: keep sparring source grounding controls honest

---
 .../features/sparring/SparringSetup.tsx       | 31 ++++++++++---------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/src/components/features/sparring/SparringSetup.tsx b/src/components/features/sparring/SparringSetup.tsx
index 76fc32b5e..3b236db2b 100644
--- a/src/components/features/sparring/SparringSetup.tsx
+++ b/src/components/features/sparring/SparringSetup.tsx
@@ -3,7 +3,6 @@ import { BookOpenCheck, Shield, Sparkles, Swords, Zap } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 import { Label } from '@/components/ui/label';
-import { Switch } from '@/components/ui/switch';
 import { Textarea } from '@/components/ui/textarea';
 import { ModelSelector } from '@/components/ModelSelector';
 import { cn } from '@/lib/utils';
@@ -46,10 +45,15 @@ export function SparringSetup({ onStart, isStarting = false, defaultMotion = ''
   const [motion, setMotion] = useState(defaultMotion);
   const [side, setSide] = useState<'pro' | 'con'>('pro');
   const [difficulty, setDifficulty] = useState<SparringDifficulty>('competitive');
-  const [useActiveSources, setUseActiveSources] = useState(true);
   const activeSourceCount = useSessionStore((state) => state.sourceLibrary.filter((source) => source.isActive).length);
 
-  const validation = useMemo(() => SparringSetupSchema.safeParse({ motion, side, difficulty, useActiveSources }), [motion, side, difficulty, useActiveSources]);
+  // The existing authenticated Ask transport always sends active library
+  // sources. Keep the setup honest instead of exposing a switch we cannot
+  // enforce without changing the deployed backend.
+  const validation = useMemo(
+    () => SparringSetupSchema.safeParse({ motion, side, difficulty, useActiveSources: true }),
+    [motion, side, difficulty],
+  );
 
   const handleStart = () => {
     if (!validation.success) return;
@@ -142,19 +146,16 @@ export function SparringSetup({ onStart, isStarting = false, defaultMotion = ''
         </Card>
 
         <Card className="border-border/70 bg-card/70">
-          <CardContent className="flex items-start justify-between gap-4 pt-6">
-            <div>
-              <div className="flex items-center gap-2 font-medium">
-                <BookOpenCheck className="h-4 w-4 text-primary" />
-                Use active sources
-              </div>
-              <p className="mt-1 text-xs leading-relaxed text-muted-foreground">
-                {activeSourceCount > 0
-                  ? `${activeSourceCount} active ${activeSourceCount === 1 ? 'source is' : 'sources are'} available as grounding context.`
-                  : 'No active sources are currently selected. The opponent will avoid inventing evidence.'}
-              </p>
+          <CardContent className="pt-6">
+            <div className="flex items-center gap-2 font-medium">
+              <BookOpenCheck className="h-4 w-4 text-primary" />
+              Active Source Library grounding
             </div>
-            <Switch checked={useActiveSources} onCheckedChange={setUseActiveSources} aria-label="Use active sources for sparring" />
+            <p className="mt-1 text-xs leading-relaxed text-muted-foreground">
+              {activeSourceCount > 0
+                ? `${activeSourceCount} active ${activeSourceCount === 1 ? 'source will' : 'sources will'} be sent as grounding context through the existing AI transport.`
+                : 'No active sources are selected. The opponent is instructed to challenge unsupported claims instead of inventing evidence.'}
+            </p>
           </CardContent>
         </Card>
 

From 6e0bf887600c15989be2be13693036f16b473fbb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:32:35 +0200
Subject: [PATCH 18/84] test: cover sparring local history store

---
 src/test/stores/sparring-store.test.ts | 86 ++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 src/test/stores/sparring-store.test.ts

diff --git a/src/test/stores/sparring-store.test.ts b/src/test/stores/sparring-store.test.ts
new file mode 100644
index 000000000..1bffcc25a
--- /dev/null
+++ b/src/test/stores/sparring-store.test.ts
@@ -0,0 +1,86 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { useSparringStore } from '@/lib/stores/sparring-store';
+import type { SparringScorecard } from '@/lib/ai/schemas/sparring';
+
+const scorecard: SparringScorecard = {
+  verdict: 'close',
+  summary: 'Both sides created offense, but the comparison remained underdeveloped.',
+  biggestImprovement: 'Compare probability before introducing another argument.',
+  strengths: ['The opening had a clear causal warrant.'],
+  missedArguments: ['The rebuttal did not answer the opponent impact.'],
+  categories: [
+    { category: 'argument-strength', rating: 'strong', evidence: 'The opening linked the policy to the stated harm.', advice: 'Keep the same causal structure.' },
+    { category: 'warrant-quality', rating: 'solid', evidence: 'The second link was asserted more than explained.', advice: 'Explain the mechanism explicitly.' },
+    { category: 'engagement', rating: 'solid', evidence: 'The rebuttal answered the opponent claim but not its impact.', advice: 'Answer offense all the way through impact.' },
+    { category: 'weighing', rating: 'needs-work', evidence: 'No direct magnitude or probability comparison appeared.', advice: 'End rebuttal with a comparative weighing sentence.' },
+  ],
+  nextDrill: 'Give a 60-second rebuttal that contains one explicit probability comparison.',
+};
+
+describe('sparring-store', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    useSparringStore.setState({ sessions: [], activeSessionId: null });
+  });
+
+  it('starts a session and makes it active', () => {
+    const session = useSparringStore.getState().startSession({
+      motion: 'This House would ban targeted advertising to minors.',
+      side: 'pro',
+      difficulty: 'competitive',
+      useActiveSources: true,
+    });
+
+    const state = useSparringStore.getState();
+    expect(state.activeSessionId).toBe(session.id);
+    expect(state.sessions).toHaveLength(1);
+    expect(state.sessions[0].status).toBe('active');
+  });
+
+  it('records turns and completes the scorecard', () => {
+    const store = useSparringStore.getState();
+    const session = store.startSession({
+      motion: 'This House would require social media platforms to verify user age.',
+      side: 'con',
+      difficulty: 'brutal',
+      useActiveSources: true,
+    });
+
+    store.addTurn(session.id, { role: 'user', phase: 'opening', content: 'Age verification creates privacy risks because identity data becomes centralized.' });
+    store.addTurn(session.id, { role: 'ai', phase: 'opening', content: 'The policy can use privacy-preserving verification and reduces exposure to harmful content.' });
+    store.completeSession(session.id, scorecard);
+
+    const saved = useSparringStore.getState().sessions[0];
+    expect(saved.turns).toHaveLength(2);
+    expect(saved.status).toBe('complete');
+    expect(saved.scorecard?.biggestImprovement).toContain('Compare probability');
+  });
+
+  it('deletes a session and clears the active id', () => {
+    const store = useSparringStore.getState();
+    const session = store.startSession({
+      motion: 'This House supports mandatory voting in national elections.',
+      side: 'pro',
+      difficulty: 'beginner',
+      useActiveSources: true,
+    });
+
+    store.deleteSession(session.id);
+    expect(useSparringStore.getState().sessions).toHaveLength(0);
+    expect(useSparringStore.getState().activeSessionId).toBeNull();
+  });
+
+  it('caps persisted history to thirty sessions', () => {
+    const store = useSparringStore.getState();
+    for (let index = 0; index < 35; index += 1) {
+      store.startSession({
+        motion: `This House would adopt policy number ${index} for public debate practice.`,
+        side: index % 2 === 0 ? 'pro' : 'con',
+        difficulty: 'competitive',
+        useActiveSources: true,
+      });
+    }
+
+    expect(useSparringStore.getState().sessions).toHaveLength(30);
+  });
+});

From 19454fcd67f1ce59745baf60f5a664df8919e46f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:33:04 +0200
Subject: [PATCH 19/84] test: cover sparring opponent and scorecard contracts

---
 src/test/ai/sparring-client.test.ts | 106 ++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 src/test/ai/sparring-client.test.ts

diff --git a/src/test/ai/sparring-client.test.ts b/src/test/ai/sparring-client.test.ts
new file mode 100644
index 000000000..03f1a5322
--- /dev/null
+++ b/src/test/ai/sparring-client.test.ts
@@ -0,0 +1,106 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@/lib/ai/client', () => ({
+  AIResponseError: class AIResponseError extends Error {
+    details?: Record<string, unknown>;
+    constructor(message: string, options?: { details?: Record<string, unknown> }) {
+      super(message);
+      this.name = 'AIResponseError';
+      this.details = options?.details;
+    }
+  },
+  askChat: vi.fn(),
+}));
+
+import { askChat } from '@/lib/ai/client';
+import { requestSparringOpponent, requestSparringScorecard } from '@/lib/ai/sparring-client';
+import type { SparringSession } from '@/lib/ai/schemas/sparring';
+
+const config = { provider: 'google', model: 'gemini-3-flash-preview', temperature: 0.75 };
+
+const session: SparringSession = {
+  id: 'spar_test',
+  setup: {
+    motion: 'This House would ban targeted advertising to minors.',
+    side: 'pro',
+    difficulty: 'competitive',
+    useActiveSources: true,
+  },
+  turns: [
+    { id: 'u1', role: 'user', phase: 'opening', content: 'Targeted advertising exploits information asymmetry and encourages harmful consumption.', createdAt: 1 },
+    { id: 'a1', role: 'ai', phase: 'opening', content: 'A ban is overbroad and less effective than enforcing transparency and data minimization.', createdAt: 2 },
+    { id: 'u2', role: 'user', phase: 'rebuttal', content: 'Transparency does not remove the incentive to optimize manipulation against minors.', createdAt: 3 },
+    { id: 'a2', role: 'ai', phase: 'rebuttal', content: 'The user still has not shown that a categorical ban outperforms narrower privacy rules.', createdAt: 4 },
+  ],
+  status: 'active',
+  createdAt: 1,
+  updatedAt: 4,
+};
+
+function askOutput(response: string) {
+  return {
+    response,
+    followUpQuestions: [],
+    uncertainties: [],
+  };
+}
+
+const scorecard = {
+  verdict: 'ai-edge',
+  summary: 'The user had a plausible harm but did not win the policy comparison.',
+  biggestImprovement: 'Compare the ban directly against the narrower alternative.',
+  strengths: ['The rebuttal identified why transparency alone may not change incentives.'],
+  missedArguments: ['No direct answer to the overbreadth objection.'],
+  categories: [
+    { category: 'argument-strength', rating: 'solid', evidence: 'The opening identified information asymmetry as the core harm.', advice: 'Tie the harm to the necessity of a ban.' },
+    { category: 'warrant-quality', rating: 'solid', evidence: 'The manipulation mechanism was asserted but not fully developed.', advice: 'Explain why minors are uniquely vulnerable.' },
+    { category: 'impact-analysis', rating: 'needs-work', evidence: 'The user did not compare the scale of the harm with the costs of a categorical ban.', advice: 'Quantify or at least comparatively weigh the affected harms.' },
+    { category: 'engagement', rating: 'solid', evidence: 'The rebuttal answered transparency but not overbreadth.', advice: 'Answer every independent piece of opponent offense.' },
+    { category: 'rebuttal-efficiency', rating: 'solid', evidence: 'The response was concise and on-clash.', advice: 'Use the saved time to answer the alternative policy.' },
+    { category: 'weighing', rating: 'needs-work', evidence: 'There was no explicit probability or comparative solvency weighing.', advice: 'End with why your mechanism solves more reliably.' },
+    { category: 'evidence-use', rating: 'needs-work', evidence: 'No evidence was cited in the typed transcript.', advice: 'Use one sourced fact only where it advances a contested warrant.' },
+    { category: 'strategy', rating: 'needs-work', evidence: 'The round allowed the narrower-alternative framing to become decisive.', advice: 'Preempt alternatives in the opening or collapse onto why they fail.' },
+  ],
+  nextDrill: 'Give a 60-second comparative rebuttal against transparency-only regulation.',
+};
+
+describe('sparring-client', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('parses a structured opponent response from Ask', async () => {
+    vi.mocked(askChat).mockResolvedValueOnce(askOutput(JSON.stringify({
+      speech: 'Your ban still has to beat a narrower privacy rule that addresses the same targeting problem.',
+      pressurePoints: ['No comparative solvency against narrower regulation.'],
+    })) as never);
+
+    const result = await requestSparringOpponent(session, session.turns[2].content, config);
+    expect(result.speech).toContain('narrower privacy rule');
+    expect(result.pressurePoints).toHaveLength(1);
+    expect(vi.mocked(askChat).mock.calls[0][0]).toContain('Respond to the user\'s actual arguments');
+  });
+
+  it('keeps useful plain-text opponent output instead of discarding it', async () => {
+    vi.mocked(askChat).mockResolvedValueOnce(askOutput('You never answered why a narrower rule cannot solve the same harm.') as never);
+    const result = await requestSparringOpponent(session, session.turns[2].content, config);
+    expect(result.speech).toContain('narrower rule');
+    expect(result.pressurePoints).toEqual([]);
+  });
+
+  it('parses the qualitative scorecard and forbids fake delivery judging in the prompt', async () => {
+    vi.mocked(askChat).mockResolvedValueOnce(askOutput(`\`\`\`json\n${JSON.stringify(scorecard)}\n\`\`\``) as never);
+    const result = await requestSparringScorecard(session, config);
+    expect(result.verdict).toBe('ai-edge');
+    expect(result.categories).toHaveLength(8);
+    expect(vi.mocked(askChat).mock.calls[0][0]).toContain('Do not infer delivery, tone of voice');
+  });
+
+  it('repairs a malformed scorecard once before failing', async () => {
+    vi.mocked(askChat)
+      .mockResolvedValueOnce(askOutput('not json') as never)
+      .mockResolvedValueOnce(askOutput(JSON.stringify(scorecard)) as never);
+
+    const result = await requestSparringScorecard(session, config);
+    expect(result.nextDrill).toContain('comparative rebuttal');
+    expect(vi.mocked(askChat)).toHaveBeenCalledTimes(2);
+  });
+});

From 7cc1b3cb1d66ca7e574f4a7c74f95d93fbd60766 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:33:38 +0200
Subject: [PATCH 20/84] test: include sparring in authenticated route smoke

---
 e2e/authed-pages.spec.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/e2e/authed-pages.spec.ts b/e2e/authed-pages.spec.ts
index 5b0fa3ae8..d4f94af4d 100644
--- a/e2e/authed-pages.spec.ts
+++ b/e2e/authed-pages.spec.ts
@@ -9,6 +9,7 @@ const AUTH_ROUTES = [
   { path: '/app/brainstorm', name: 'brainstorm' },
   { path: '/app/factoids', name: 'factoids' },
   { path: '/app/ask', name: 'ask' },
+  { path: '/app/sparring', name: 'sparring' },
   { path: '/app/library', name: 'library' },
   { path: '/app/history', name: 'history' },
   { path: '/app/timer', name: 'timer' },

From ae2239e275fcc4e735eba6f3848d228622948f5b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Wed, 26 Aug 2026 23:34:32 +0200
Subject: [PATCH 21/84] test: add deterministic sparring browser journey

---
 e2e/sparring-flow.spec.ts | 79 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 e2e/sparring-flow.spec.ts

diff --git a/e2e/sparring-flow.spec.ts b/e2e/sparring-flow.spec.ts
new file mode 100644
index 000000000..9e3ac2220
--- /dev/null
+++ b/e2e/sparring-flow.spec.ts
@@ -0,0 +1,79 @@
+import { test, expect } from '@playwright/test';
+import { stubSupabaseSession, setLocale } from './helpers/auth';
+
+const scorecard = {
+  verdict: 'user-edge',
+  summary: 'The user won the central mechanism clash and did more comparative weighing in rebuttal.',
+  biggestImprovement: 'Front-load the comparison against narrower alternatives in the opening.',
+  strengths: ['The rebuttal directly answered the opponent mechanism.'],
+  missedArguments: ['The opening did not preempt the narrower-policy alternative.'],
+  categories: [
+    { category: 'argument-strength', rating: 'strong', evidence: 'The user established a clear participation benefit.', advice: 'Keep the causal claim this explicit.' },
+    { category: 'warrant-quality', rating: 'solid', evidence: 'The participation mechanism was plausible but brief.', advice: 'Add one more causal link.' },
+    { category: 'impact-analysis', rating: 'solid', evidence: 'The user explained why access matters but did not compare scale in the opening.', advice: 'Make the affected population comparative.' },
+    { category: 'engagement', rating: 'strong', evidence: 'The rebuttal answered the opponent funding alternative directly.', advice: 'Keep organizing rebuttal around their offense.' },
+    { category: 'rebuttal-efficiency', rating: 'strong', evidence: 'The response spent its time on the decisive alternative-policy clash.', advice: 'Preserve this collapse discipline.' },
+    { category: 'weighing', rating: 'solid', evidence: 'The user compared access, but not probability explicitly.', advice: 'Add a one-sentence probability comparison.' },
+    { category: 'evidence-use', rating: 'needs-work', evidence: 'No source was cited in the typed round.', advice: 'Use evidence only where it resolves a contested factual warrant.' },
+    { category: 'strategy', rating: 'strong', evidence: 'The rebuttal collapsed onto why the alternative did not solve access.', advice: 'Preempt that alternative earlier next time.' },
+  ],
+  nextDrill: 'Give a 60-second opening that preempts one narrower counter-policy before the opponent raises it.',
+};
+
+test('sparring completes a full deterministic training loop', async ({ page }) => {
+  await setLocale(page, 'en');
+  await stubSupabaseSession(page);
+
+  let aiCall = 0;
+  await page.route('**/functions/v1/ai', async (route) => {
+    const headers = {
+      'access-control-allow-origin': '*',
+      'access-control-allow-headers': 'authorization, x-client-info, apikey, content-type',
+      'content-type': 'application/json',
+    };
+    if (route.request().method() === 'OPTIONS') {
+      await route.fulfill({ status: 200, headers, body: 'ok' });
+      return;
+    }
+
+    aiCall += 1;
+    const response = aiCall === 1
+      ? JSON.stringify({
+          speech: 'A universal free-transit policy is expensive. Targeted discounts can improve access while preserving funding for service quality.',
+          pressurePoints: ['You have not shown why targeted support cannot solve the same access problem.'],
+        })
+      : aiCall === 2
+        ? JSON.stringify({
+            speech: 'You still need to prove that universal access creates more benefit than investing the same budget in frequency and reliability.',
+            pressurePoints: ['The budget tradeoff is still underdeveloped.'],
+          })
+        : JSON.stringify(scorecard);
+
+    await route.fulfill({
+      status: 200,
+      headers,
+      body: JSON.stringify({ output: { response, followUpQuestions: [], uncertainties: [] } }),
+    });
+  });
+
+  await page.goto('/app/sparring');
+  await page.getByLabel('Motion').fill('This House would make public transport free at the point of use.');
+  await page.getByRole('button', { name: 'Start sparring' }).click();
+
+  const speechBox = page.locator('textarea').first();
+  await speechBox.fill('Free public transport removes a direct price barrier and lets more people participate in work, education, and public life.');
+  await page.getByRole('button', { name: 'Send opening' }).click();
+  await expect(page.getByText(/universal free-transit policy is expensive/i)).toBeVisible();
+  await expect(page.getByText(/targeted support/i)).toBeVisible();
+
+  await speechBox.fill('Targeted discounts preserve eligibility gaps and administrative friction, while universal access removes the barrier for every marginal trip.');
+  await page.getByRole('button', { name: 'Send rebuttal' }).click();
+  await expect(page.getByText(/frequency and reliability/i)).toBeVisible();
+
+  await page.getByRole('button', { name: 'Finish and get scorecard' }).click();
+  await expect(page.getByText('Your side had the edge')).toBeVisible();
+  await expect(page.getByText(/Front-load the comparison against narrower alternatives/i)).toBeVisible();
+  await expect(page.getByText('Weighing')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Rematch this motion' })).toBeVisible();
+  expect(aiCall).toBe(3);
+});

From b00f258ac7c018af1080d9952743ee8b07dba810 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:15:15 +0200
Subject: [PATCH 22/84] fix: export sparring phase type

---
 src/lib/ai/schemas/sparring.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/lib/ai/schemas/sparring.ts b/src/lib/ai/schemas/sparring.ts
index 71ccfe749..232cad5d3 100644
--- a/src/lib/ai/schemas/sparring.ts
+++ b/src/lib/ai/schemas/sparring.ts
@@ -65,6 +65,8 @@ export const SparringSessionSchema = z.object({
 
 export type SparringSide = z.infer<typeof SparringSideSchema>;
 export type SparringDifficulty = z.infer<typeof SparringDifficultySchema>;
+export type SparringTurnRole = z.infer<typeof SparringTurnRoleSchema>;
+export type SparringTurnPhase = z.infer<typeof SparringTurnPhaseSchema>;
 export type SparringTurn = z.infer<typeof SparringTurnSchema>;
 export type SparringSetup = z.infer<typeof SparringSetupSchema>;
 export type SparringOpponentOutput = z.infer<typeof SparringOpponentOutputSchema>;

From 4e924cbf53bc51c25a1feed67fc1950e5d5c70c1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:15:28 +0200
Subject: [PATCH 23/84] fix: validate persisted sparring history

---
 src/lib/stores/sparring-store.ts | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/src/lib/stores/sparring-store.ts b/src/lib/stores/sparring-store.ts
index 229920f09..72b626434 100644
--- a/src/lib/stores/sparring-store.ts
+++ b/src/lib/stores/sparring-store.ts
@@ -1,10 +1,11 @@
 import { create } from 'zustand';
 import { persist } from 'zustand/middleware';
-import type {
-  SparringScorecard,
-  SparringSession,
-  SparringSetup,
-  SparringTurn,
+import {
+  SparringSessionSchema,
+  type SparringScorecard,
+  type SparringSession,
+  type SparringSetup,
+  type SparringTurn,
 } from '@/lib/ai/schemas/sparring';
 
 const MAX_SAVED_SESSIONS = 30;
@@ -13,6 +14,16 @@ function makeId(prefix: string) {
   return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
 }
 
+function parsePersistedSessions(value: unknown): SparringSession[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .flatMap((candidate) => {
+      const parsed = SparringSessionSchema.safeParse(candidate);
+      return parsed.success ? [parsed.data] : [];
+    })
+    .slice(0, MAX_SAVED_SESSIONS);
+}
+
 interface SparringState {
   sessions: SparringSession[];
   activeSessionId: string | null;
@@ -26,7 +37,7 @@ interface SparringState {
 
 export const useSparringStore = create<SparringState>()(
   persist(
-    (set, get) => ({
+    (set) => ({
       sessions: [],
       activeSessionId: null,
 
@@ -83,11 +94,11 @@ export const useSparringStore = create<SparringState>()(
       partialize: (state) => ({ sessions: state.sessions, activeSessionId: state.activeSessionId }),
       merge: (persisted, current) => {
         const saved = persisted as Partial<SparringState> | undefined;
-        const sessions = Array.isArray(saved?.sessions) ? saved.sessions.slice(0, MAX_SAVED_SESSIONS) : [];
+        const sessions = parsePersistedSessions(saved?.sessions);
         const activeSessionId = typeof saved?.activeSessionId === 'string' && sessions.some((session) => session.id === saved.activeSessionId)
           ? saved.activeSessionId
           : null;
-        return { ...current, ...saved, sessions, activeSessionId } as SparringState;
+        return { ...current, sessions, activeSessionId };
       },
     },
   ),

From 3e5b3405b2d25d3eabe72aadcbb92fc25136b3dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:15:51 +0200
Subject: [PATCH 24/84] fix: clear sparring data across auth boundaries

---
 src/lib/supabase/AuthProvider.tsx | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/lib/supabase/AuthProvider.tsx b/src/lib/supabase/AuthProvider.tsx
index 24773791b..8c8759e65 100644
--- a/src/lib/supabase/AuthProvider.tsx
+++ b/src/lib/supabase/AuthProvider.tsx
@@ -4,6 +4,7 @@ import type { Session, User } from '@supabase/supabase-js';
 import { supabase } from './client';
 import { useSessionStore } from '@/lib/stores/session-store';
 import { useSettingsStore } from '@/lib/stores/settings-store';
+import { useSparringStore } from '@/lib/stores/sparring-store';
 import { getOAuthRedirectUrl, openExternalUrl } from '@/lib/native';
 import { setJamUserId } from '@/lib/jam-metadata';
 
@@ -40,6 +41,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
   const hydrateSettingsStore = useSettingsStore((state) => state.hydrateFromServer);
   const resetSessionStore = useSessionStore((state) => state.resetLocalData);
   const resetSettingsStore = useSettingsStore((state) => state.resetLocalData);
+  const resetSparringStore = useSparringStore((state) => state.clearSparringHistory);
   const currentUserIdRef = useRef<string | undefined>(undefined);
 
   useEffect(() => {
@@ -157,6 +159,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
         hydratedUserId = undefined;
         resetSessionStore();
         resetSettingsStore();
+        resetSparringStore();
         sessionStorage.removeItem('google_provider_token');
         localStorage.removeItem('google_provider_token');
         // Remove refresh tokens written by older clients as well; this client
@@ -169,6 +172,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
         hydratedUserId = undefined;
         resetSessionStore();
         resetSettingsStore();
+        resetSparringStore();
       }
 
       hydrateStores(nextUserId);
@@ -178,7 +182,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
       mounted = false;
       authListener.subscription.unsubscribe();
     };
-  }, [hydrateSessionStore, hydrateSettingsStore, resetSessionStore, resetSettingsStore]);
+  }, [hydrateSessionStore, hydrateSettingsStore, resetSessionStore, resetSettingsStore, resetSparringStore]);
 
   const value = useMemo<AuthContextValue>(() => ({
     session,
@@ -209,8 +213,9 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
       await supabase.auth.signOut();
       resetSessionStore();
       resetSettingsStore();
+      resetSparringStore();
     },
-  }), [session, loading, resetSessionStore, resetSettingsStore]);
+  }), [session, loading, resetSessionStore, resetSettingsStore, resetSparringStore]);
 
   return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
 }

From d4752dd7db029146624552034ee55f510d266f26 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:16:16 +0200
Subject: [PATCH 25/84] fix: make sparring source grounding explicit

---
 .../features/sparring/SparringSetup.tsx       | 30 +++++++++++--------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/src/components/features/sparring/SparringSetup.tsx b/src/components/features/sparring/SparringSetup.tsx
index 3b236db2b..6d7144dc7 100644
--- a/src/components/features/sparring/SparringSetup.tsx
+++ b/src/components/features/sparring/SparringSetup.tsx
@@ -1,4 +1,5 @@
 import { useMemo, useState } from 'react';
+import { Link } from 'react-router-dom';
 import { BookOpenCheck, Shield, Sparkles, Swords, Zap } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
@@ -47,9 +48,9 @@ export function SparringSetup({ onStart, isStarting = false, defaultMotion = ''
   const [difficulty, setDifficulty] = useState<SparringDifficulty>('competitive');
   const activeSourceCount = useSessionStore((state) => state.sourceLibrary.filter((source) => source.isActive).length);
 
-  // The existing authenticated Ask transport always sends active library
-  // sources. Keep the setup honest instead of exposing a switch we cannot
-  // enforce without changing the deployed backend.
+  // Sparring uses the same active-source selection as the rest of DebateLab.
+  // This is intentionally not a per-round toggle: the shared AI client always
+  // includes active sources, so exposing an OFF switch here would be dishonest.
   const validation = useMemo(
     () => SparringSetupSchema.safeParse({ motion, side, difficulty, useActiveSources: true }),
     [motion, side, difficulty],
@@ -70,7 +71,7 @@ export function SparringSetup({ onStart, isStarting = false, defaultMotion = ''
             </div>
             <div>
               <CardTitle>Set up a round</CardTitle>
-              <CardDescription>Start small: two speeches from you, two from the AI, then an evidence-backed scorecard.</CardDescription>
+              <CardDescription>Two speeches from you, two from the AI, then a transcript-grounded scorecard.</CardDescription>
             </div>
           </div>
         </CardHeader>
@@ -147,15 +148,20 @@ export function SparringSetup({ onStart, isStarting = false, defaultMotion = ''
 
         <Card className="border-border/70 bg-card/70">
           <CardContent className="pt-6">
-            <div className="flex items-center gap-2 font-medium">
-              <BookOpenCheck className="h-4 w-4 text-primary" />
-              Active Source Library grounding
+            <div className="flex items-start gap-3">
+              <BookOpenCheck className="mt-0.5 h-4 w-4 shrink-0 text-primary" />
+              <div>
+                <div className="font-medium">Active Source Library grounding</div>
+                <p className="mt-1 text-xs leading-relaxed text-muted-foreground">
+                  {activeSourceCount > 0
+                    ? `${activeSourceCount} active ${activeSourceCount === 1 ? 'source is' : 'sources are'} available to the opponent as factual grounding.`
+                    : 'No active sources are selected, so the opponent is instructed not to manufacture evidence.'}
+                </p>
+                <Button asChild variant="link" size="sm" className="mt-1 h-auto px-0 text-xs">
+                  <Link to="/app/library">Manage active sources</Link>
+                </Button>
+              </div>
             </div>
-            <p className="mt-1 text-xs leading-relaxed text-muted-foreground">
-              {activeSourceCount > 0
-                ? `${activeSourceCount} active ${activeSourceCount === 1 ? 'source will' : 'sources will'} be sent as grounding context through the existing AI transport.`
-                : 'No active sources are selected. The opponent is instructed to challenge unsupported claims instead of inventing evidence.'}
-            </p>
           </CardContent>
         </Card>
 

From e07749ac5a7086e819890854694abbd87139e826 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:16:37 +0200
Subject: [PATCH 26/84] fix: allow retrying failed sparring opponent turns

---
 .../features/sparring/SparringRound.tsx       | 20 ++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/src/components/features/sparring/SparringRound.tsx b/src/components/features/sparring/SparringRound.tsx
index 98d23ac48..4a60bb5a1 100644
--- a/src/components/features/sparring/SparringRound.tsx
+++ b/src/components/features/sparring/SparringRound.tsx
@@ -1,5 +1,5 @@
 import { useMemo, useState } from 'react';
-import { Bot, Flag, Send, UserRound } from 'lucide-react';
+import { Bot, Flag, RefreshCcw, Send, UserRound } from 'lucide-react';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
@@ -13,22 +13,24 @@ interface SparringRoundProps {
   isThinking: boolean;
   pressurePoints: string[];
   onSubmitSpeech: (content: string, phase: SparringTurnPhase) => Promise<void> | void;
+  onRetryOpponent: () => Promise<void> | void;
   onFinish: () => Promise<void> | void;
 }
 
-export function SparringRound({ session, isThinking, pressurePoints, onSubmitSpeech, onFinish }: SparringRoundProps) {
+export function SparringRound({ session, isThinking, pressurePoints, onSubmitSpeech, onRetryOpponent, onFinish }: SparringRoundProps) {
   const [draft, setDraft] = useState('');
   const userTurns = session.turns.filter((turn) => turn.role === 'user').length;
   const aiTurns = session.turns.filter((turn) => turn.role === 'ai').length;
   const phase: SparringTurnPhase = userTurns === 0 ? 'opening' : 'rebuttal';
   const canSubmit = draft.trim().length >= 20 && !isThinking && userTurns < 2 && userTurns === aiTurns;
+  const canRetryOpponent = !isThinking && userTurns === aiTurns + 1;
   const canFinish = userTurns >= 2 && aiTurns >= 2 && !isThinking;
 
   const roundLabel = useMemo(() => {
     if (userTurns === 0) return 'Your opening';
     if (userTurns === 1 && aiTurns === 1) return 'Your rebuttal';
     if (userTurns >= 2 && aiTurns >= 2) return 'Round complete';
-    return 'Opponent responding';
+    return 'Opponent response pending';
   }, [userTurns, aiTurns]);
 
   const submit = async () => {
@@ -82,6 +84,18 @@ export function SparringRound({ session, isThinking, pressurePoints, onSubmitSpe
               </CardContent>
             </Card>
           )}
+
+          {canRetryOpponent && (
+            <Card className="mr-auto max-w-[92%] border-amber-500/30 bg-amber-500/5">
+              <CardContent className="flex flex-col gap-3 pt-6 sm:flex-row sm:items-center sm:justify-between">
+                <p className="text-sm text-muted-foreground">Your speech is saved, but the opponent response did not complete. Retry without retyping your argument.</p>
+                <Button variant="outline" onClick={onRetryOpponent}>
+                  <RefreshCcw className="mr-2 h-4 w-4" />
+                  Retry opponent
+                </Button>
+              </CardContent>
+            </Card>
+          )}
         </div>
 
         {userTurns < 2 ? (

From e51301916b3a74eb68655e4ebb362a8ed3b71262 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:17:04 +0200
Subject: [PATCH 27/84] feat: respect output language in sparring prompts

---
 src/lib/ai/sparring-client.ts | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/lib/ai/sparring-client.ts b/src/lib/ai/sparring-client.ts
index 324b5277e..6a936573d 100644
--- a/src/lib/ai/sparring-client.ts
+++ b/src/lib/ai/sparring-client.ts
@@ -8,6 +8,7 @@ import {
   type SparringSession,
   type SparringTurn,
 } from '@/lib/ai/schemas/sparring';
+import { useSettingsStore } from '@/lib/stores/settings-store';
 
 function opposingSide(side: 'pro' | 'con') {
   return side === 'pro' ? 'con' : 'pro';
@@ -25,6 +26,12 @@ function difficultyInstruction(difficulty: SparringSession['setup']['difficulty'
   }
 }
 
+function outputLanguageInstruction() {
+  const language = useSettingsStore.getState().outputLanguage;
+  const label = language === 'es' ? 'Spanish' : language === 'hu' ? 'Hungarian' : 'English';
+  return `${label} (${language})`;
+}
+
 function transcript(turns: SparringTurn[]) {
   return turns.map((turn, index) => {
     const speaker = turn.role === 'user' ? 'USER' : 'AI OPPONENT';
@@ -60,6 +67,7 @@ User side: ${session.setup.side}
 Your side: ${aiSide}
 Difficulty: ${session.setup.difficulty}
 Difficulty instruction: ${difficultyInstruction(session.setup.difficulty)}
+Response language: ${outputLanguageInstruction()}. Write the speech and pressure points in this language.
 
 Round transcript so far:
 ${transcript(session.turns)}
@@ -83,6 +91,7 @@ Motion: ${session.setup.motion}
 User side: ${session.setup.side}
 AI opponent side: ${opposingSide(session.setup.side)}
 Difficulty: ${session.setup.difficulty}
+Response language: ${outputLanguageInstruction()}. Write every user-facing field in this language.
 Active Source Library grounding was ${session.setup.useActiveSources ? 'enabled' : 'not requested'} for the round.
 
 FULL TRANSCRIPT:

From 1371e2e8cf93ba8a6e51d4b1b1b88915fe74c06d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:17:27 +0200
Subject: [PATCH 28/84] feat: connect sparring feedback to prep tools

---
 .../features/sparring/SparringScorecard.tsx   | 47 ++++++++++++++++---
 1 file changed, 41 insertions(+), 6 deletions(-)

diff --git a/src/components/features/sparring/SparringScorecard.tsx b/src/components/features/sparring/SparringScorecard.tsx
index 278df0cfd..27709f44a 100644
--- a/src/components/features/sparring/SparringScorecard.tsx
+++ b/src/components/features/sparring/SparringScorecard.tsx
@@ -1,4 +1,4 @@
-import { ArrowRight, CheckCircle2, FileDown, FileText, MessageCircle, RefreshCcw, Target, Trophy } from 'lucide-react';
+import { ArrowRight, BookOpenCheck, CheckCircle2, FileDown, FileText, Lightbulb, MessageCircle, RefreshCcw, Swords, Target, Trophy } from 'lucide-react';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
@@ -10,6 +10,9 @@ interface SparringScorecardProps {
   scorecard: SparringScorecardType;
   onRematch: () => void;
   onDiscuss: () => void;
+  onAttackRound: () => void;
+  onBrainstormMissed: () => void;
+  onVerifyOpening: () => void;
   onNewRound: () => void;
   onExportDocx: () => void;
   onExportPdf: () => void;
@@ -32,7 +35,18 @@ function ratingClass(rating: SparringScorecardType['categories'][number]['rating
   return 'border-primary/25 bg-primary/10 text-primary';
 }
 
-export function SparringScorecard({ session, scorecard, onRematch, onDiscuss, onNewRound, onExportDocx, onExportPdf }: SparringScorecardProps) {
+export function SparringScorecard({
+  session,
+  scorecard,
+  onRematch,
+  onDiscuss,
+  onAttackRound,
+  onBrainstormMissed,
+  onVerifyOpening,
+  onNewRound,
+  onExportDocx,
+  onExportPdf,
+}: SparringScorecardProps) {
   const verdictLabel = scorecard.verdict === 'user-edge'
     ? 'Your side had the edge'
     : scorecard.verdict === 'ai-edge'
@@ -120,15 +134,36 @@ export function SparringScorecard({ session, scorecard, onRematch, onDiscuss, on
         </Card>
       </div>
 
+      <Card className="border-border/70 bg-card/60">
+        <CardHeader className="pb-3">
+          <CardTitle className="text-base">Keep working from this round</CardTitle>
+          <CardDescription>Carry the actual transcript and motion into DebateLab's existing prep tools instead of starting from scratch.</CardDescription>
+        </CardHeader>
+        <CardContent className="flex flex-col gap-2 sm:flex-row sm:flex-wrap">
+          <Button variant="outline" onClick={onDiscuss}>
+            <MessageCircle className="mr-2 h-4 w-4" />
+            Discuss with Ask
+          </Button>
+          <Button variant="outline" onClick={onAttackRound}>
+            <Swords className="mr-2 h-4 w-4" />
+            Attack my round
+          </Button>
+          <Button variant="outline" onClick={onBrainstormMissed}>
+            <Lightbulb className="mr-2 h-4 w-4" />
+            Find arguments I missed
+          </Button>
+          <Button variant="outline" onClick={onVerifyOpening}>
+            <BookOpenCheck className="mr-2 h-4 w-4" />
+            Verify my opening
+          </Button>
+        </CardContent>
+      </Card>
+
       <div className="flex flex-col gap-2 sm:flex-row sm:flex-wrap">
         <Button onClick={onRematch}>
           <RefreshCcw className="mr-2 h-4 w-4" />
           Rematch this motion
         </Button>
-        <Button variant="outline" onClick={onDiscuss}>
-          <MessageCircle className="mr-2 h-4 w-4" />
-          Discuss with Ask
-        </Button>
         <Button variant="outline" onClick={onExportDocx}>
           <FileText className="mr-2 h-4 w-4" />
           Export Word

From 5e989105d6ea9586e86db7f657493f798b66e655 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:18:15 +0200
Subject: [PATCH 29/84] feat: complete sparring recovery and tool handoffs

---
 src/pages/SparringPage.tsx | 101 ++++++++++++++++++++++++++++++++++---
 1 file changed, 95 insertions(+), 6 deletions(-)

diff --git a/src/pages/SparringPage.tsx b/src/pages/SparringPage.tsx
index a56504153..51a4464e1 100644
--- a/src/pages/SparringPage.tsx
+++ b/src/pages/SparringPage.tsx
@@ -26,6 +26,13 @@ function transcriptText(turns: SparringTurn[]) {
   return turns.map((turn, index) => `${index + 1}. ${turn.role === 'user' ? 'You' : 'AI opponent'} (${turn.phase}): ${turn.content}`).join('\n\n');
 }
 
+function userAdvocacyText(turns: SparringTurn[]) {
+  return turns
+    .filter((turn) => turn.role === 'user')
+    .map((turn) => `${turn.phase.toUpperCase()}:\n${turn.content}`)
+    .join('\n\n');
+}
+
 export default function SparringPage() {
   const navigate = useNavigate();
   const { toast } = useToast();
@@ -38,7 +45,15 @@ export default function SparringPage() {
   const addTurn = useSparringStore((state) => state.addTurn);
   const completeSession = useSparringStore((state) => state.completeSession);
   const setActiveSession = useSparringStore((state) => state.setActiveSession);
-  const { addAskMessage, setAskLoading, askMessages } = useSessionStore();
+  const activeSourceCount = useSessionStore((state) => state.sourceLibrary.filter((source) => source.isActive).length);
+  const {
+    addAskMessage,
+    setAskLoading,
+    askMessages,
+    setAttackForm,
+    setBrainstormForm,
+    setFactoidsForm,
+  } = useSessionStore();
   const [isThinking, setIsThinking] = useState(false);
   const [isScoring, setIsScoring] = useState(false);
   const [pressurePoints, setPressurePoints] = useState<string[]>([]);
@@ -62,7 +77,7 @@ export default function SparringPage() {
     captureProductEvent('sparring_started', {
       difficulty: setup.difficulty,
       side: setup.side,
-      active_sources: setup.useActiveSources,
+      active_sources: activeSourceCount,
     });
     setActiveSession(created.id);
   };
@@ -97,19 +112,48 @@ export default function SparringPage() {
     }
   };
 
+  const handleRetryOpponent = async () => {
+    if (!session || isThinking) return;
+    const current = getSparringSession(session.id);
+    if (!current) return;
+    const userTurns = current.turns.filter((turn) => turn.role === 'user');
+    const aiTurns = current.turns.filter((turn) => turn.role === 'ai');
+    if (userTurns.length !== aiTurns.length + 1) return;
+    const latestUserTurn = [...current.turns].reverse().find((turn) => turn.role === 'user');
+    if (!latestUserTurn) return;
+
+    setIsThinking(true);
+    try {
+      const opponent = await requestSparringOpponent(current, latestUserTurn.content, config);
+      addTurn(current.id, { role: 'ai', phase: latestUserTurn.phase, content: opponent.speech });
+      setPressurePoints(opponent.pressurePoints);
+      captureProductEvent('sparring_turn_completed', {
+        phase: latestUserTurn.phase,
+        speaker: 'ai',
+        retry: true,
+        pressure_points: opponent.pressurePoints.length,
+      });
+    } catch (error) {
+      handleAIError(error, 'Opponent retry failed');
+    } finally {
+      setIsThinking(false);
+    }
+  };
+
   const handleFinish = async () => {
     if (!session || isScoring) return;
     const current = getSparringSession(session.id);
     if (!current || current.turns.filter((turn) => turn.role === 'user').length < 2 || current.turns.filter((turn) => turn.role === 'ai').length < 2) return;
 
     setIsScoring(true);
-    captureProductEvent('sparring_completed', {
-      difficulty: current.setup.difficulty,
-      turns: current.turns.length,
-    });
     try {
       const scorecard = await requestSparringScorecard(current, config);
       completeSession(current.id, scorecard);
+      captureProductEvent('sparring_completed', {
+        difficulty: current.setup.difficulty,
+        turns: current.turns.length,
+        verdict: scorecard.verdict,
+      });
       captureProductEvent('sparring_scorecard_viewed', {
         verdict: scorecard.verdict,
         difficulty: current.setup.difficulty,
@@ -153,6 +197,47 @@ export default function SparringPage() {
     }
   };
 
+  const handleAttackRound = () => {
+    if (!session) return;
+    setAttackForm({
+      caseText: `Motion: ${session.setup.motion}\nSide: ${session.setup.side}\n\n${userAdvocacyText(session.turns)}`,
+      aggressiveness: 'ruthless',
+      judgeParadigm: 'logic',
+      detectFallacies: true,
+      analyzeWeighing: true,
+    });
+    captureProductEvent('sparring_feedback_action_used', { action: 'attack_round' });
+    navigate('/app/attack');
+  };
+
+  const handleBrainstormMissed = () => {
+    if (!session) return;
+    setBrainstormForm({
+      motion: session.setup.motion,
+      side: session.setup.side,
+      outputMode: 'topfive',
+      context: `Use this completed practice round to find better arguments, extensions, and responses for my side.\n\nTranscript:\n${transcriptText(session.turns)}\n\nScorecard missed opportunities:\n${session.scorecard?.missedArguments.join('\n') || 'None listed.'}`,
+    });
+    captureProductEvent('sparring_feedback_action_used', { action: 'brainstorm_missed' });
+    navigate('/app/brainstorm');
+  };
+
+  const handleVerifyOpening = () => {
+    if (!session) return;
+    const opening = session.turns.find((turn) => turn.role === 'user' && turn.phase === 'opening');
+    if (!opening) return;
+    setFactoidsForm({
+      claim: opening.content,
+      direction: 'for',
+      region: 'Global',
+      sourceType: 'any',
+      timeframe: 'Recent (last 5 years)',
+      sourceCount: 5,
+    });
+    captureProductEvent('sparring_feedback_action_used', { action: 'verify_opening' });
+    navigate('/app/factoids');
+  };
+
   const handleExportDocx = async () => {
     if (!session) return;
     const ok = await exportSparringToDocx(session);
@@ -215,6 +300,9 @@ export default function SparringPage() {
               scorecard={session.scorecard}
               onRematch={handleRematch}
               onDiscuss={handleDiscuss}
+              onAttackRound={handleAttackRound}
+              onBrainstormMissed={handleBrainstormMissed}
+              onVerifyOpening={handleVerifyOpening}
               onNewRound={handleNewRound}
               onExportDocx={handleExportDocx}
               onExportPdf={handleExportPdf}
@@ -227,6 +315,7 @@ export default function SparringPage() {
               isThinking={isThinking}
               pressurePoints={pressurePoints}
               onSubmitSpeech={handleSubmitSpeech}
+              onRetryOpponent={handleRetryOpponent}
               onFinish={handleFinish}
             />
           </AnimatedSection>

From 8d71154710e56b42de661629ddb5893285709ade Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:18:52 +0200
Subject: [PATCH 30/84] fix: provide sparring navigation copy fallback

---
 src/pages/HomePage.tsx | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/src/pages/HomePage.tsx b/src/pages/HomePage.tsx
index b82055036..c7e49fd87 100644
--- a/src/pages/HomePage.tsx
+++ b/src/pages/HomePage.tsx
@@ -57,8 +57,14 @@ export default function HomePage() {
                     </div>
                     <ArrowRight className="h-4 w-4 text-muted-foreground transition-all group-hover:translate-x-1 group-hover:text-primary" />
                   </div>
-                  <CardTitle className="text-lg">{t(`home.${mode.key}`)}</CardTitle>
-                  <CardDescription>{t(`home.${mode.key}Desc`)}</CardDescription>
+                  <CardTitle className="text-lg">
+                    {mode.key === 'sparring' ? t('home.sparring', 'Sparring') : t(`home.${mode.key}`)}
+                  </CardTitle>
+                  <CardDescription>
+                    {mode.key === 'sparring'
+                      ? t('home.sparringDesc', 'Practice live clash against an AI opponent and get transcript-grounded feedback.')
+                      : t(`home.${mode.key}Desc`)}
+                  </CardDescription>
                 </CardHeader>
               </Card>
             </Link>

From 2bfe6950494b5a46b38b7f38664caab2d8b7b985 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:19:11 +0200
Subject: [PATCH 31/84] fix: render sparring navigation labels cleanly

---
 src/components/layout/AppLayout.tsx | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/src/components/layout/AppLayout.tsx b/src/components/layout/AppLayout.tsx
index 4527b5392..f6ccae4a7 100644
--- a/src/components/layout/AppLayout.tsx
+++ b/src/components/layout/AppLayout.tsx
@@ -42,6 +42,11 @@ export function AppLayout() {
   const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
   const { t } = useTranslation();
 
+  const navLabel = (key: string) => key === 'sparring' ? t('nav.sparring', 'Sparring') : t(`nav.${key}`);
+  const navDescription = (key: string) => key === 'sparring'
+    ? t('navDesc.sparring', 'Practice live clash')
+    : t(`navDesc.${key}`);
+
   return (
     <div className="native-safe-screen flex flex-col bg-background">
       {/* Header */}
@@ -71,7 +76,7 @@ export function AppLayout() {
                 activeClassName="bg-primary/10 text-primary nav-active-pill"
               >
                 <item.icon className="h-4 w-4 shrink-0" />
-                <span className="hidden xl:inline">{t(`nav.${item.key}`)}</span>
+                <span className="hidden xl:inline">{navLabel(item.key)}</span>
               </NavLink>
             ))}
           </nav>
@@ -115,8 +120,8 @@ export function AppLayout() {
                 >
                   <item.icon className="h-5 w-5" />
                   <div>
-                    <div className="font-medium">{t(`nav.${item.key}`)}</div>
-                    <div className="text-xs opacity-70">{t(`navDesc.${item.key}`)}</div>
+                    <div className="font-medium">{navLabel(item.key)}</div>
+                    <div className="text-xs opacity-70">{navDescription(item.key)}</div>
                   </div>
                 </NavLink>
               ))}

From e99708d3288372a0b0208883d6fd914dbd332e34 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:19:35 +0200
Subject: [PATCH 32/84] test: cover sparring persistence safety

---
 src/test/stores/sparring-store.test.ts | 29 ++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/src/test/stores/sparring-store.test.ts b/src/test/stores/sparring-store.test.ts
index 1bffcc25a..510de5ffa 100644
--- a/src/test/stores/sparring-store.test.ts
+++ b/src/test/stores/sparring-store.test.ts
@@ -70,6 +70,20 @@ describe('sparring-store', () => {
     expect(useSparringStore.getState().activeSessionId).toBeNull();
   });
 
+  it('clears all local sparring history at an auth boundary', () => {
+    const store = useSparringStore.getState();
+    store.startSession({
+      motion: 'This House would require open primaries in national elections.',
+      side: 'con',
+      difficulty: 'competitive',
+      useActiveSources: true,
+    });
+
+    store.clearSparringHistory();
+    expect(useSparringStore.getState().sessions).toEqual([]);
+    expect(useSparringStore.getState().activeSessionId).toBeNull();
+  });
+
   it('caps persisted history to thirty sessions', () => {
     const store = useSparringStore.getState();
     for (let index = 0; index < 35; index += 1) {
@@ -83,4 +97,19 @@ describe('sparring-store', () => {
 
     expect(useSparringStore.getState().sessions).toHaveLength(30);
   });
+
+  it('drops malformed localStorage sessions instead of trusting persisted data', async () => {
+    localStorage.setItem('debatelab-sparring', JSON.stringify({
+      state: {
+        sessions: [{ id: 'broken', setup: { motion: 42 }, turns: 'not-an-array' }],
+        activeSessionId: 'broken',
+      },
+      version: 0,
+    }));
+
+    await useSparringStore.persist.rehydrate();
+
+    expect(useSparringStore.getState().sessions).toEqual([]);
+    expect(useSparringStore.getState().activeSessionId).toBeNull();
+  });
 });

From 584f1205b5aa1cc2a1b0c7dfe21d3ee5065f95df Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:21:53 +0200
Subject: [PATCH 33/84] test: cover sparring recovery and tool handoff

---
 e2e/sparring-flow.spec.ts | 70 +++++++++++++++++++++++++++++++--------
 1 file changed, 57 insertions(+), 13 deletions(-)

diff --git a/e2e/sparring-flow.spec.ts b/e2e/sparring-flow.spec.ts
index 9e3ac2220..6df865c96 100644
--- a/e2e/sparring-flow.spec.ts
+++ b/e2e/sparring-flow.spec.ts
@@ -20,19 +20,26 @@ const scorecard = {
   nextDrill: 'Give a 60-second opening that preempts one narrower counter-policy before the opponent raises it.',
 };
 
-test('sparring completes a full deterministic training loop', async ({ page }) => {
+function askEnvelope(response: string) {
+  return JSON.stringify({ output: { response, followUpQuestions: [], uncertainties: [] } });
+}
+
+const corsHeaders = {
+  'access-control-allow-origin': '*',
+  'access-control-allow-headers': 'authorization, x-client-info, apikey, content-type',
+  'content-type': 'application/json',
+};
+
+test.beforeEach(async ({ page }) => {
   await setLocale(page, 'en');
   await stubSupabaseSession(page);
+});
 
+test('sparring completes a deterministic training loop and hands the round to Attack', async ({ page }) => {
   let aiCall = 0;
   await page.route('**/functions/v1/ai', async (route) => {
-    const headers = {
-      'access-control-allow-origin': '*',
-      'access-control-allow-headers': 'authorization, x-client-info, apikey, content-type',
-      'content-type': 'application/json',
-    };
     if (route.request().method() === 'OPTIONS') {
-      await route.fulfill({ status: 200, headers, body: 'ok' });
+      await route.fulfill({ status: 200, headers: corsHeaders, body: 'ok' });
       return;
     }
 
@@ -49,11 +56,7 @@ test('sparring completes a full deterministic training loop', async ({ page }) =
           })
         : JSON.stringify(scorecard);
 
-    await route.fulfill({
-      status: 200,
-      headers,
-      body: JSON.stringify({ output: { response, followUpQuestions: [], uncertainties: [] } }),
-    });
+    await route.fulfill({ status: 200, headers: corsHeaders, body: askEnvelope(response) });
   });
 
   await page.goto('/app/sparring');
@@ -61,7 +64,8 @@ test('sparring completes a full deterministic training loop', async ({ page }) =
   await page.getByRole('button', { name: 'Start sparring' }).click();
 
   const speechBox = page.locator('textarea').first();
-  await speechBox.fill('Free public transport removes a direct price barrier and lets more people participate in work, education, and public life.');
+  const opening = 'Free public transport removes a direct price barrier and lets more people participate in work, education, and public life.';
+  await speechBox.fill(opening);
   await page.getByRole('button', { name: 'Send opening' }).click();
   await expect(page.getByText(/universal free-transit policy is expensive/i)).toBeVisible();
   await expect(page.getByText(/targeted support/i)).toBeVisible();
@@ -76,4 +80,44 @@ test('sparring completes a full deterministic training loop', async ({ page }) =
   await expect(page.getByText('Weighing')).toBeVisible();
   await expect(page.getByRole('button', { name: 'Rematch this motion' })).toBeVisible();
   expect(aiCall).toBe(3);
+
+  await page.getByRole('button', { name: 'Attack my round' }).click();
+  await expect(page).toHaveURL(/\/app\/attack$/);
+  await expect(page.locator('#caseText')).toContainText('');
+  await expect(page.locator('#caseText')).toHaveValue(new RegExp(opening.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+});
+
+test('sparring can retry a failed opponent response without losing the user speech', async ({ page }) => {
+  let aiCall = 0;
+  await page.route('**/functions/v1/ai', async (route) => {
+    if (route.request().method() === 'OPTIONS') {
+      await route.fulfill({ status: 200, headers: corsHeaders, body: 'ok' });
+      return;
+    }
+
+    aiCall += 1;
+    const response = aiCall === 1
+      ? ''
+      : JSON.stringify({
+          speech: 'A narrower subsidy still leaves eligibility friction, but you need to show why that friction is large enough to justify universality.',
+          pressurePoints: ['Quantify or comparatively explain the eligibility-friction harm.'],
+        });
+    await route.fulfill({ status: 200, headers: corsHeaders, body: askEnvelope(response) });
+  });
+
+  await page.goto('/app/sparring');
+  await page.getByLabel('Motion').fill('This House would make public transport free at the point of use.');
+  await page.getByRole('button', { name: 'Start sparring' }).click();
+
+  const opening = 'Universal access removes price and eligibility friction at the same time, increasing participation across marginal trips.';
+  await page.locator('textarea').first().fill(opening);
+  await page.getByRole('button', { name: 'Send opening' }).click();
+
+  await expect(page.getByText(opening)).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Retry opponent' })).toBeVisible();
+  await page.getByRole('button', { name: 'Retry opponent' }).click();
+
+  await expect(page.getByText(/narrower subsidy still leaves eligibility friction/i)).toBeVisible();
+  await expect(page.getByText(opening)).toHaveCount(1);
+  expect(aiCall).toBe(2);
 });

From f16f4d64834dd05fbafe03a513ff9173ec14afca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:22:16 +0200
Subject: [PATCH 34/84] test: retain browser failure evidence

---
 playwright.config.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/playwright.config.ts b/playwright.config.ts
index 97c7daaa2..766eafcf9 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -10,10 +10,12 @@ export default defineConfig({
   retries: process.env.CI ? 2 : 0,
   workers: process.env.CI ? 2 : undefined,
   reporter: process.env.CI ? [['github'], ['html', { open: 'never' }]] : 'list',
+  outputDir: 'test-results',
   use: {
     baseURL,
-    trace: 'on-first-retry',
+    trace: 'retain-on-failure',
     screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
     locale: 'en-US',
   },
   projects: [

From ba83fadb2c18effe210adc50d4610d2e5f5c85f6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:22:38 +0200
Subject: [PATCH 35/84] test: make verify include browser journeys

---
 package.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 3572f0058..6d80d589d 100644
--- a/package.json
+++ b/package.json
@@ -20,7 +20,8 @@
     "test:watch": "vitest",
     "test:e2e": "playwright test",
     "test:e2e:ui": "playwright test --ui",
-    "verify": "npm run lint && npm run typecheck && npm test -- --coverage && npm run build"
+    "verify:core": "npm run lint && npm run typecheck && npm test -- --coverage && npm run build",
+    "verify": "npm run verify:core && npm run test:e2e"
   },
   "dependencies": {
     "@capacitor/app": "^8.1.0",

From 5a1f83f3551cd2d424a1dcbcda17733275978232 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:22:51 +0200
Subject: [PATCH 36/84] ci: gate pull requests on browser verification

---
 .github/workflows/deploy.yml | 23 ++++++++++++++---------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index d13f94abf..8c765cf29 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -32,17 +32,22 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Lint
-        run: npm run lint
+      - name: Install Playwright Chromium
+        run: npx playwright install --with-deps chromium
 
-      - name: Typecheck
-        run: npm run typecheck
+      - name: Verify
+        run: npm run verify
 
-      - name: Test
-        run: npm test -- --coverage
-
-      - name: Build
-        run: npm run build
+      - name: Upload browser failure evidence
+        if: failure()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: playwright-failure-evidence-${{ github.run_id }}
+          path: |
+            test-results
+            playwright-report
+          if-no-files-found: ignore
+          retention-days: 7
 
       - name: Set up QEMU
         if: env.DOCKER_PUSH == 'true'

From b1b99c08669a12f25e4510aec7356f09104002b0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:23:22 +0200
Subject: [PATCH 37/84] docs: add agent verification contract

---
 AGENTS.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 149 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..2fead68e1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,149 @@
+# DebateLab Agent Guide
+
+This file is the verification contract for coding agents working in DebateLab. Read it before changing code.
+
+## Runtime and package manager
+
+- Node.js: 22.x
+- Package manager: npm (`package-lock.json` is canonical)
+- Web app dev port: 8080 by default
+- Local Supabase port used by existing tooling: 54321
+- Production web app: `https://debate.pi-stack.org`
+- Frontend: Vite + React + TypeScript
+- Backend source: Supabase Edge Functions and SQL migrations under `supabase/`
+
+## Canonical verification
+
+After `npm ci`, install the browser once on a new machine:
+
+```bash
+npx playwright install chromium
+```
+
+On Linux CI or a fresh Linux host where system browser dependencies are missing:
+
+```bash
+npx playwright install --with-deps chromium
+```
+
+Then the canonical branch verification command is:
+
+```bash
+npm run verify
+```
+
+`npm run verify` must run, in order:
+
+1. ESLint
+2. TypeScript typechecking
+3. Vitest with the configured coverage thresholds
+4. Production Vite build
+5. Playwright deterministic browser journeys
+
+Useful narrower commands:
+
+```bash
+npm run verify:core
+npm run lint
+npm run typecheck
+npm test
+npm run test:coverage
+npm run build
+npm run test:e2e
+npm run test:e2e:ui
+```
+
+Do not report a change as verified if the relevant command did not execute. A GitHub Actions job that failed before obtaining a runner, with no executed steps, is infrastructure failure rather than a failed test result.
+
+## Verification ladder
+
+Use the smallest useful rung while developing, then run the full gate before considering the work complete:
+
+1. Static checks for edited TypeScript/React.
+2. Focused Vitest tests for the changed behavior.
+3. Full coverage-gated Vitest suite.
+4. Production build.
+5. Deterministic Playwright browser journeys.
+6. Live authenticated staging checks only when explicitly authorized and staging credentials already exist.
+7. Manual browser inspection only for visual judgment that automated assertions cannot establish.
+
+Every bug fix should gain a failing regression test first when practical. Never weaken an assertion or coverage threshold merely to make a branch green.
+
+## Browser failure evidence
+
+Playwright retains trace, screenshot, and video for failures. CI uploads `test-results/` and `playwright-report/` as a short-lived artifact when verification fails.
+
+When describing verification evidence, name the command or CI run. Do not say that a browser flow passed based only on code review.
+
+## Authentication and environment model
+
+Supabase credentials are selected in `src/lib/supabase/env.ts`.
+
+- Production project ref: `uziwdtkzofptihahfooo`
+- Staging project ref: `brifeyypjauyusmkptkx`
+- Runtime storage key: `debate-supabase-env`
+- Auth storage is environment-specific.
+
+The normal Playwright suite uses a deliberately fake localStorage session and mocks network behavior where a product journey needs backend output. That suite is safe for pull requests because it receives no privileged credential and does not mutate Supabase.
+
+A real staging-authenticated suite, when present, is a separate opt-in verification path. It must never run on untrusted pull-request code with staging secrets.
+
+## Supabase deployment boundary
+
+Source files under `supabase/functions/` and `supabase/migrations/` may be reviewed and changed when a task requires it, but source control and deployment are separate operations.
+
+**Do not perform any of these unless the user explicitly authorizes that exact operation:**
+
+- `supabase db push`
+- applying a migration to local/staging/production through a connected remote project
+- `supabase functions deploy`
+- `supabase secrets set`
+- linking or relinking the repository to a different remote project for deployment
+- modifying production or staging rows as a substitute for a test fixture
+
+For the `feature/sparring-verification-retention-loop` work, all Supabase deployment and mutation is explicitly out of scope. Keep migrations/functions un-applied and use deterministic mocks for executable CI.
+
+The existing `demo-code-login` endpoint is stateful: it reserves a demo-code use and may provision/update a user. Do not invoke it merely to prove a branch works when remote Supabase mutation is not authorized.
+
+## Secrets
+
+Never commit, print, paste into a PR comment, or expose in test artifacts:
+
+- service-role keys
+- provider API keys
+- Stripe secrets
+- demo-code pepper values
+- plaintext reusable demo access codes
+
+Public Supabase anon credentials are browser credentials, not server secrets, but still do not invent or rotate them casually.
+
+## AI product rules
+
+DebateLab is a debate-preparation and training product. User-facing AI behavior should preserve these invariants:
+
+- Do not fabricate evidence, citations, statistics, quotations, or source metadata.
+- Weak research sources are fallback context, not citation-quality evidence.
+- Controls must be honest: a visible toggle must actually change the request or deterministic post-processing behavior.
+- Typed Sparring cannot honestly judge vocal delivery, eye contact, speaking pace, or other audio-only qualities.
+- Prefer transcript-specific feedback over unexplained numeric scores.
+- Active Source Library items are factual grounding context; make that behavior visible rather than pretending a disabled control exists.
+
+## Sparring architecture
+
+Sparring deliberately avoids adding another feature branch to the large `supabase/functions/ai/index.ts` handler.
+
+- Schema: `src/lib/ai/schemas/sparring.ts`
+- AI orchestration: `src/lib/ai/sparring-client.ts`
+- Local persisted history: `src/lib/stores/sparring-store.ts`
+- UI: `src/components/features/sparring/` and `src/pages/SparringPage.tsx`
+- Export: `src/lib/sparring-export.ts`
+
+The first version is a four-speech loop: user opening, AI response, user rebuttal, AI response, then a qualitative scorecard. Completed sessions are local-first and must be cleared at auth boundaries so one browser account cannot inherit another account's transcripts.
+
+## Roadmap authority
+
+`plans/README.md` is the roadmap index, but the source tree is authoritative. Before implementing a plan, check whether the described files/behavior already exist. When a plan is substantially implemented, update the index so future agents do not repeatedly rebuild shipped work.
+
+## Pull requests and merging
+
+A draft PR may be used to obtain CI evidence. Do not merge a PR unless the user explicitly requests a merge. Do not enable auto-merge as a substitute for explicit authorization.

From 47d1264ed2bdcff88acf07778124fa39c760a5e9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:24:22 +0200
Subject: [PATCH 38/84] test: support deterministic staging frontend selection

---
 src/lib/supabase/env.ts | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/src/lib/supabase/env.ts b/src/lib/supabase/env.ts
index 12fb48a46..c6fb0ad7d 100644
--- a/src/lib/supabase/env.ts
+++ b/src/lib/supabase/env.ts
@@ -1,7 +1,7 @@
 /**
  * Runtime environment resolver for Supabase.
- * Reads localStorage to determine whether to use prod or staging credentials.
- * Only admin users should toggle this via the Settings → Developer panel.
+ * Reads localStorage first, then an optional Vite build/dev override.
+ * Only admin users should toggle the persisted environment via Settings → Developer.
  */
 
 export type SupabaseEnv = 'production' | 'staging';
@@ -15,16 +15,21 @@ const ENVS: Record<SupabaseEnv, { url: string; anonKey: string }> = {
   },
   staging: {
     url: 'https://brifeyypjauyusmkptkx.supabase.co',
-    anonKey: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImJyaWZleXlwamF1eXVzbWtwdGt4Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzkyNTI5NjEsImV4cCI6MjA5NDgyODk2MX0.xKYcvponjw5b_ouPhJDnSBBB1CUSw1Jpz35zGiMmH6A',
+    anonKey: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXAiLCJyZWYiOiJicmlmZXl5cGphdXl1c21rcHRreCIsInJvbGUiOiJhbm9uIiwiaWF0IjoxNzc5MjUyOTYxLCJleHAiOjIwOTQ4Mjg5NjF9.xKYcvponjw5b_ouPhJDnSBBB1CUSw1Jpz35zGiMmH6A',
   },
 };
 
+function forcedEnv(): SupabaseEnv | null {
+  const value = import.meta.env.VITE_FORCE_SUPABASE_ENV;
+  return value === 'staging' || value === 'production' ? value : null;
+}
+
 export function getActiveEnv(): SupabaseEnv {
   try {
     const stored = localStorage.getItem(STORAGE_KEY);
     if (stored === 'staging') return 'staging';
   } catch { /* SSR or restricted storage */ }
-  return 'production';
+  return forcedEnv() ?? 'production';
 }
 
 export function setActiveEnv(env: SupabaseEnv): void {

From 4dd6edeb1c577783e59e3c8d883fb0b22a224bc5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:24:40 +0200
Subject: [PATCH 39/84] fix: preserve staging anon credential exactly

---
 src/lib/supabase/env.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/lib/supabase/env.ts b/src/lib/supabase/env.ts
index c6fb0ad7d..283e1fa96 100644
--- a/src/lib/supabase/env.ts
+++ b/src/lib/supabase/env.ts
@@ -15,7 +15,7 @@ const ENVS: Record<SupabaseEnv, { url: string; anonKey: string }> = {
   },
   staging: {
     url: 'https://brifeyypjauyusmkptkx.supabase.co',
-    anonKey: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXAiLCJyZWYiOiJicmlmZXl5cGphdXl1c21rcHRreCIsInJvbGUiOiJhbm9uIiwiaWF0IjoxNzc5MjUyOTYxLCJleHAiOjIwOTQ4Mjg5NjF9.xKYcvponjw5b_ouPhJDnSBBB1CUSw1Jpz35zGiMmH6A',
+    anonKey: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImJyaWZleXlwamF1eXVzbWtwdGt4Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzkyNTI5NjEsImV4cCI6MjA5NDgyODk2MX0.xKYcvponjw5b_ouPhJDnSBBB1CUSw1Jpz35zGiMmH6A',
   },
 };
 

From fac1ec33575e7fe2fbb4f86c5a05b4849ccf2cd7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:25:03 +0200
Subject: [PATCH 40/84] test: isolate stateful staging browser suite

---
 playwright.config.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/playwright.config.ts b/playwright.config.ts
index 766eafcf9..d13e5c90d 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -5,6 +5,7 @@ const baseURL = process.env.PLAYWRIGHT_BASE_URL || `http://localhost:${PORT}`;
 
 export default defineConfig({
   testDir: './e2e',
+  testIgnore: '**/staging/**',
   fullyParallel: true,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,

From f815fba253d987b966296a2d90818e222187e768 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:25:11 +0200
Subject: [PATCH 41/84] test: prepare opt-in authenticated staging suite

---
 playwright.staging.config.ts | 51 ++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 playwright.staging.config.ts

diff --git a/playwright.staging.config.ts b/playwright.staging.config.ts
new file mode 100644
index 000000000..36d6eb700
--- /dev/null
+++ b/playwright.staging.config.ts
@@ -0,0 +1,51 @@
+import { defineConfig, devices } from '@playwright/test';
+
+const PORT = Number(process.env.PORT || 8080);
+const baseURL = process.env.STAGING_PLAYWRIGHT_BASE_URL || `http://localhost:${PORT}`;
+const authFile = 'test-results/.auth/staging.json';
+
+export default defineConfig({
+  testDir: './e2e/staging',
+  fullyParallel: false,
+  forbidOnly: true,
+  retries: 0,
+  workers: 1,
+  reporter: [['list'], ['html', { outputFolder: 'playwright-report-staging', open: 'never' }]],
+  outputDir: 'test-results-staging',
+  use: {
+    baseURL,
+    trace: 'retain-on-failure',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    locale: 'en-US',
+  },
+  projects: [
+    {
+      name: 'staging-auth-setup',
+      testMatch: /auth\.setup\.ts/,
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'staging-desktop-chromium',
+      testIgnore: /auth\.setup\.ts/,
+      dependencies: ['staging-auth-setup'],
+      use: {
+        ...devices['Desktop Chrome'],
+        viewport: { width: 1280, height: 800 },
+        storageState: authFile,
+      },
+    },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: baseURL,
+    reuseExistingServer: false,
+    timeout: 120_000,
+    stdout: 'ignore',
+    stderr: 'pipe',
+    env: {
+      ...process.env,
+      VITE_FORCE_SUPABASE_ENV: 'staging',
+    },
+  },
+});

From fd85cebb56fcd6584395265fd49e7fc49867c98a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:25:25 +0200
Subject: [PATCH 42/84] test: add real staging auth setup

---
 e2e/staging/auth.setup.ts | 66 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 e2e/staging/auth.setup.ts

diff --git a/e2e/staging/auth.setup.ts b/e2e/staging/auth.setup.ts
new file mode 100644
index 000000000..f971f9b60
--- /dev/null
+++ b/e2e/staging/auth.setup.ts
@@ -0,0 +1,66 @@
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { test as setup, expect } from '@playwright/test';
+import { createClient } from '@supabase/supabase-js';
+
+const authFile = 'test-results/.auth/staging.json';
+
+function requireEnv(name: string): string {
+  const value = process.env[name]?.trim();
+  if (!value) {
+    throw new Error(`${name} is required for the stateful staging E2E suite. This suite must not run in ordinary pull-request CI.`);
+  }
+  return value;
+}
+
+setup('authenticate against the pre-provisioned staging demo account', async ({ page, request, baseURL }) => {
+  const supabaseUrl = requireEnv('E2E_STAGING_SUPABASE_URL').replace(/\/$/, '');
+  const anonKey = requireEnv('E2E_STAGING_ANON_KEY');
+  const demoCode = requireEnv('E2E_STAGING_DEMO_CODE');
+  const appBaseUrl = baseURL || 'http://localhost:8080';
+
+  // This endpoint is intentionally stateful: it consumes a demo-code use and
+  // may provision/update the corresponding demo account. Never call this setup
+  // merely to verify an untrusted pull request.
+  const login = await request.post(`${supabaseUrl}/functions/v1/demo-code-login`, {
+    headers: {
+      apikey: anonKey,
+      authorization: `Bearer ${anonKey}`,
+      origin: appBaseUrl,
+      'content-type': 'application/json',
+    },
+    data: {
+      code: demoCode,
+      browserFingerprint: `debatelab-playwright-${Date.now()}`,
+      redirectTo: `${appBaseUrl}/app`,
+    },
+  });
+
+  expect(login.ok(), `demo-code-login failed with HTTP ${login.status()}`).toBeTruthy();
+  const handoff = await login.json() as { tokenHash?: string; type?: string; error?: string };
+  expect(handoff.tokenHash, handoff.error || 'demo-code-login did not return a token hash').toBeTruthy();
+
+  const client = createClient(supabaseUrl, anonKey, {
+    auth: {
+      persistSession: false,
+      autoRefreshToken: false,
+      detectSessionInUrl: false,
+    },
+  });
+  const { data, error } = await client.auth.verifyOtp({
+    token_hash: handoff.tokenHash!,
+    type: 'magiclink',
+  });
+  if (error || !data.session) {
+    throw new Error(`Staging OTP verification failed: ${error?.message || 'no session returned'}`);
+  }
+
+  await page.goto('/');
+  await page.evaluate((session) => {
+    window.localStorage.setItem('debate-supabase-env', 'staging');
+    window.localStorage.setItem('debate-auth-staging', JSON.stringify(session));
+  }, data.session);
+
+  await mkdir(dirname(authFile), { recursive: true });
+  await page.context().storageState({ path: authFile });
+});

From 820e9df00dfa790c28c29e1b9b77cb46a446c615 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:25:38 +0200
Subject: [PATCH 43/84] test: add authenticated staging canary

---
 e2e/staging/authenticated.spec.ts | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)
 create mode 100644 e2e/staging/authenticated.spec.ts

diff --git a/e2e/staging/authenticated.spec.ts b/e2e/staging/authenticated.spec.ts
new file mode 100644
index 000000000..5cf67b1b7
--- /dev/null
+++ b/e2e/staging/authenticated.spec.ts
@@ -0,0 +1,28 @@
+import { test, expect } from '@playwright/test';
+
+test('real staging session survives reload and stays inside the protected app', async ({ page }) => {
+  await page.goto('/app');
+  await expect(page.locator('body')).toBeVisible();
+  expect(page.url()).not.toContain('/login');
+
+  await page.reload({ waitUntil: 'domcontentloaded' });
+  await expect(page.locator('body')).toBeVisible();
+  expect(page.url()).not.toContain('/login');
+});
+
+test('real staging auth can complete one Sparring opponent turn', async ({ page }) => {
+  test.setTimeout(180_000);
+
+  await page.goto('/app/sparring');
+  await page.getByLabel('Motion').fill('This House would require social media platforms to offer a chronological feed by default.');
+  await page.getByRole('button', { name: 'Start sparring' }).click();
+
+  await page.locator('textarea').first().fill(
+    'A chronological default reduces platform incentives to maximize engagement through opaque ranking, while still letting users opt into recommendations if they want them.',
+  );
+  await page.getByRole('button', { name: 'Send opening' }).click();
+
+  // The text is rendered only after the authenticated AI request completes.
+  await expect(page.getByText('AI opponent')).toBeVisible({ timeout: 150_000 });
+  await expect(page.getByRole('button', { name: 'Send rebuttal' })).toBeVisible();
+});

From 6b0435fed127af950a2511e6b0368adc56da3493 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:25:56 +0200
Subject: [PATCH 44/84] chore: ignore staging browser artifacts

---
 .gitignore | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.gitignore b/.gitignore
index 049ad9846..aefdf2aa9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -34,7 +34,9 @@ coverage/
 
 # Playwright artifacts
 test-results/
+test-results-staging/
 playwright-report/
+playwright-report-staging/
 playwright/.cache/
 
 # Deploy tool state

From 7031d4b9f7971cc317a00b4240b9d564f9409bcc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:26:17 +0200
Subject: [PATCH 45/84] test: expose opt-in staging verification command

---
 package.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/package.json b/package.json
index 6d80d589d..8df01c3b2 100644
--- a/package.json
+++ b/package.json
@@ -19,6 +19,7 @@
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "test:e2e": "playwright test",
+    "test:e2e:staging": "playwright test -c playwright.staging.config.ts",
     "test:e2e:ui": "playwright test --ui",
     "verify:core": "npm run lint && npm run typecheck && npm test -- --coverage && npm run build",
     "verify": "npm run verify:core && npm run test:e2e"

From c866b67ab009fb495363ab98652cda0a4b0858ed Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:26:33 +0200
Subject: [PATCH 46/84] docs: document stateful staging verification

---
 e2e/staging/README.md | 49 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 e2e/staging/README.md

diff --git a/e2e/staging/README.md b/e2e/staging/README.md
new file mode 100644
index 000000000..6106e5298
--- /dev/null
+++ b/e2e/staging/README.md
@@ -0,0 +1,49 @@
+# Stateful staging E2E
+
+This directory is deliberately excluded from the ordinary `playwright.config.ts` suite and from `npm run verify`.
+
+## Why it is separate
+
+`auth.setup.ts` calls the deployed staging `demo-code-login` Edge Function. That operation is **stateful**:
+
+- it reserves a use of the supplied demo code;
+- it can create the demo user;
+- it updates the demo user's role/settings;
+- the live Sparring canary consumes AI provider quota and writes normal usage telemetry.
+
+Do not run this suite on pull-request code merely because credentials happen to be available.
+
+## Required environment
+
+Provide these values through the shell or an approved secret store. Never commit them to the repository or print them in logs.
+
+```text
+E2E_STAGING_SUPABASE_URL
+E2E_STAGING_ANON_KEY
+E2E_STAGING_DEMO_CODE
+```
+
+The anon key is a browser credential, but keep the harness configurable so the test cannot silently point at the wrong project. The demo code is reusable access material and must be treated as a secret.
+
+Optional:
+
+```text
+STAGING_PLAYWRIGHT_BASE_URL=http://localhost:8080
+```
+
+The frontend process is forced to `VITE_FORCE_SUPABASE_ENV=staging` by `playwright.staging.config.ts`.
+
+## Run
+
+Only after remote staging mutation has been explicitly authorized:
+
+```bash
+npx playwright install chromium
+npm run test:e2e:staging
+```
+
+The setup exchanges the demo code for a real staging session and saves only the browser storage state under ignored `test-results/.auth/`. The authenticated project then verifies that the session survives reload and that one real Sparring opponent request can travel end to end.
+
+## Pull-request safety
+
+Do not add this config to ordinary pull-request CI with staging secrets. Pull-request code controls the test process and must not receive reusable staging credentials.

From 029f5354bb831c1ab812aada88dd3d6be20c521b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:28:49 +0200
Subject: [PATCH 47/84] security: bound source-import body read time

---
 .../functions/import-source/resource-limits.ts   | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/supabase/functions/import-source/resource-limits.ts b/supabase/functions/import-source/resource-limits.ts
index cdf381e22..11d2ebe4f 100644
--- a/supabase/functions/import-source/resource-limits.ts
+++ b/supabase/functions/import-source/resource-limits.ts
@@ -1,18 +1,29 @@
 export const MAX_RESPONSE_BYTES = 1_000_000;
+export const MAX_RESPONSE_READ_MS = 10_000;
 
-export async function readBoundedText(response: Response, maxBytes = MAX_RESPONSE_BYTES): Promise<string> {
+export async function readBoundedText(
+  response: Response,
+  maxBytes = MAX_RESPONSE_BYTES,
+  maxReadMs = MAX_RESPONSE_READ_MS,
+): Promise<string> {
   const declaredLength = Number(response.headers.get("content-length"));
   if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
     throw new Error("Source response exceeds the 1 MB import limit.");
   }
   if (!response.body) return "";
+
   const reader = response.body.getReader();
   const decoder = new TextDecoder();
   let received = 0;
   let text = "";
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => reject(new Error("Source response body timed out.")), maxReadMs);
+  });
+
   try {
     while (true) {
-      const { done, value } = await reader.read();
+      const { done, value } = await Promise.race([reader.read(), deadline]);
       if (done) break;
       received += value.byteLength;
       if (received > maxBytes) throw new Error("Source response exceeds the 1 MB import limit.");
@@ -20,6 +31,7 @@ export async function readBoundedText(response: Response, maxBytes = MAX_RESPONS
     }
     return text + decoder.decode();
   } finally {
+    if (timeoutId !== undefined) clearTimeout(timeoutId);
     reader.cancel().catch(() => undefined);
   }
 }

From 5654a4cebb941e19f9a1cf4d1d08bef6cf0b1646 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:29:06 +0200
Subject: [PATCH 48/84] test: cover bounded source response consumption

---
 .../import-source/resource-limits.test.ts     | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 supabase/functions/import-source/resource-limits.test.ts

diff --git a/supabase/functions/import-source/resource-limits.test.ts b/supabase/functions/import-source/resource-limits.test.ts
new file mode 100644
index 000000000..e20cb309d
--- /dev/null
+++ b/supabase/functions/import-source/resource-limits.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { readBoundedText } from './resource-limits.ts';
+
+describe('source-import resource limits', () => {
+  it('reads a normal text response', async () => {
+    const response = new Response('Debate evidence source text.');
+    await expect(readBoundedText(response, 1024, 100)).resolves.toBe('Debate evidence source text.');
+  });
+
+  it('rejects an oversized declared content length before reading', async () => {
+    const response = new Response('small', { headers: { 'content-length': '2048' } });
+    await expect(readBoundedText(response, 1024, 100)).rejects.toThrow(/exceeds the 1 MB import limit/i);
+  });
+
+  it('rejects a streamed body once the byte cap is exceeded', async () => {
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new Uint8Array(8));
+        controller.enqueue(new Uint8Array(8));
+        controller.close();
+      },
+    });
+    const response = new Response(stream);
+    await expect(readBoundedText(response, 10, 100)).rejects.toThrow(/exceeds the 1 MB import limit/i);
+  });
+
+  it('aborts body consumption when the read deadline expires', async () => {
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode('headers arrived but body never finishes'));
+      },
+    });
+    const response = new Response(stream);
+    await expect(readBoundedText(response, 1024, 5)).rejects.toThrow(/body timed out/i);
+  });
+});

From d4f6a855e65b2449e93ec80b8923b7c195b51d2a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:30:02 +0200
Subject: [PATCH 49/84] security: move source import behind fixed Exa egress

---
 supabase/functions/import-source/index.ts | 280 ++++++++--------------
 1 file changed, 99 insertions(+), 181 deletions(-)

diff --git a/supabase/functions/import-source/index.ts b/supabase/functions/import-source/index.ts
index 9e7203b9f..4434d9170 100644
--- a/supabase/functions/import-source/index.ts
+++ b/supabase/functions/import-source/index.ts
@@ -1,5 +1,5 @@
 import { createClient } from "https://esm.sh/@supabase/supabase-js@2";
-import { isPrivateIpv4, isPrivateIpv6, validatePublicHttpUrl, validateResolvedPublicHost } from "./url-validation.ts";
+import { isPrivateIpv4, isPrivateIpv6, validatePublicHttpUrl } from "./url-validation.ts";
 import { readBoundedText } from "./resource-limits.ts";
 
 // Re-export helpers so existing callers (if any) keep working.
@@ -15,9 +15,26 @@ const ALLOWED_ORIGINS = [
 ];
 
 const MAX_CONTENT_CHARS = 50_000;
+const EXA_RESPONSE_BYTES = 1_000_000;
 const FETCH_TIMEOUT_MS = 10_000;
-const MAX_REDIRECTS = 5;
 const DAILY_IMPORT_LIMIT = 50;
+const EXA_CONTENTS_URL = "https://api.exa.ai/contents";
+
+const supabaseUrl = Deno.env.get("SUPABASE_URL")!;
+const supabaseServiceKey = Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!;
+const supabase = createClient(supabaseUrl, supabaseServiceKey);
+
+type ExaContentsResult = {
+  url?: unknown;
+  title?: unknown;
+  text?: unknown;
+  author?: unknown;
+  publishedDate?: unknown;
+};
+
+type ExaContentsResponse = {
+  results?: unknown;
+};
 
 function getCorsHeaders(origin: string | null) {
   const allowedOrigin = origin && ALLOWED_ORIGINS.includes(origin) ? origin : ALLOWED_ORIGINS[0];
@@ -28,10 +45,6 @@ function getCorsHeaders(origin: string | null) {
   };
 }
 
-const supabaseUrl = Deno.env.get("SUPABASE_URL")!;
-const supabaseServiceKey = Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!;
-const supabase = createClient(supabaseUrl, supabaseServiceKey);
-
 function jsonResponse(body: unknown, status: number, headers: Record<string, string>) {
   return new Response(JSON.stringify(body), {
     status,
@@ -63,7 +76,7 @@ async function logImport(userId: string, status: "success" | "error", errorCode?
     await supabase.from("ai_requests").insert({
       user_id: userId,
       feature: "import_source",
-      provider: "url",
+      provider: "exa",
       model: "url-import",
       latency_ms: latencyMs,
       status,
@@ -74,171 +87,91 @@ async function logImport(userId: string, status: "success" | "error", errorCode?
   }
 }
 
-async function fetchWithTimeout(initialUrl: URL) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-  try {
-    let currentUrl = initialUrl;
-    for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
-      await validateResolvedPublicHost(currentUrl);
-      const response = await fetch(currentUrl.toString(), {
-        headers: {
-          "Accept": "text/html, text/plain;q=0.9, application/xhtml+xml;q=0.8",
-          "User-Agent": "DebateLabSourceImporter/1.0",
-        },
-        signal: controller.signal,
-        redirect: "manual",
-      });
-
-      // Manual redirect handling so we can re-validate against SSRF on every hop.
-      if (response.status >= 300 && response.status < 400) {
-        const location = response.headers.get("location");
-        if (!location) {
-          throw new Error("Redirect without Location header.");
-        }
-        if (hop === MAX_REDIRECTS) {
-          throw new Error("Too many redirects.");
-        }
-        const nextUrl = new URL(location, currentUrl);
-        currentUrl = validatePublicHttpUrl(nextUrl.toString());
-        continue;
-      }
-
-      return { response, finalUrl: currentUrl };
-    }
-    throw new Error("Too many redirects.");
-  } finally {
-    clearTimeout(timeout);
-  }
+function asOptionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
 
-function decodeEntities(text: string) {
+function normalizeText(text: string) {
   return text
-    .replace(/&nbsp;/gi, " ")
-    .replace(/&amp;/gi, "&")
-    .replace(/&quot;/gi, "\"")
-    .replace(/&apos;/gi, "'")
-    .replace(/&lt;/gi, "<")
-    .replace(/&gt;/gi, ">")
-    .replace(/&#x([0-9a-f]+);/gi, (_, hex) => {
-      const code = parseInt(hex, 16);
-      return Number.isFinite(code) ? String.fromCodePoint(code) : "";
-    })
-    .replace(/&#(\d+);/g, (_, dec) => {
-      const code = parseInt(dec, 10);
-      return Number.isFinite(code) ? String.fromCodePoint(code) : "";
-    });
-}
-
-function getMeta(html: string, names: string[]) {
-  for (const name of names) {
-    const pattern = new RegExp(`<meta\\s+[^>]*(?:name|property)=["']${name}["'][^>]*content=["']([^"']+)["'][^>]*>`, "i");
-    const reversePattern = new RegExp(`<meta\\s+[^>]*content=["']([^"']+)["'][^>]*(?:name|property)=["']${name}["'][^>]*>`, "i");
-    const match = html.match(pattern) || html.match(reversePattern);
-    if (match?.[1]) return decodeEntities(match[1].trim());
-  }
-  return undefined;
-}
-
-function getTitle(html: string, fallback: string) {
-  return getMeta(html, ["og:title", "twitter:title"]) ||
-    decodeEntities(html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.replace(/\s+/g, " ").trim() || "") ||
-    fallback;
+    .replace(/\r/g, "\n")
+    .replace(/[ \t]+/g, " ")
+    .replace(/\n[ \t]+/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim()
+    .slice(0, MAX_CONTENT_CHARS);
 }
 
-function stripHtml(html: string) {
-  const cleaned = html
-    .replace(/<script[\s\S]*?<\/script>/gi, " ")
-    .replace(/<style[\s\S]*?<\/style>/gi, " ")
-    .replace(/<template[\s\S]*?<\/template>/gi, " ")
-    .replace(/<noscript[\s\S]*?<\/noscript>/gi, " ")
-    .replace(/<!--[\s\S]*?-->/g, " ")
-    .replace(/<(nav|footer|header|aside|form|svg|iframe|button)[\s\S]*?<\/\1>/gi, " ")
-    .replace(/<(div|section)[^>]*role=["'](banner|navigation|complementary|search|contentinfo)["'][\s\S]*?<\/\1>/gi, " ")
-    .replace(/<(div|section)[^>]*(?:id|class)=["'][^"']*(?:cookie|consent|banner|nav(?:bar|igation)?|menu|sidebar|header|footer|subscribe|newsletter|social|share|paywall)[^"']*["'][\s\S]*?<\/\1>/gi, " ");
-
-  const candidates: string[] = [];
-  const blockPattern = /<(article|main|section|div)[^>]*(?:id|class)=["'][^"']*(?:article|content|story|post|entry|main|body|reader)[^"']*["'][^>]*>([\s\S]*?)<\/\1>/gi;
-  for (const match of cleaned.matchAll(blockPattern)) {
-    if (match[2]) candidates.push(match[2]);
+/**
+ * Fetch user-requested public content through Exa's fixed contents endpoint.
+ * The Edge Function never opens a network connection to the user-controlled
+ * hostname, which removes the DNS-rebinding/TOCTOU gap inherent in validating
+ * a hostname and then asking ordinary fetch() to resolve it again.
+ */
+async function extractViaExa(requestedUrl: URL) {
+  const apiKey = Deno.env.get("EXA_API_KEY");
+  if (!apiKey) {
+    throw new Error("Source import is unavailable because content extraction is not configured.");
   }
-  const semanticMatch = cleaned.match(/<(article|main)[^>]*>([\s\S]*?)<\/\1>/i);
-  if (semanticMatch?.[2]) candidates.push(semanticMatch[2]);
-  candidates.push(cleaned);
 
-  const textCandidates = candidates
-    .map((candidate) => htmlToText(candidate))
-    .filter((text) => text.split(/\s+/).filter(Boolean).length >= 20);
-
-  return textCandidates.sort((a, b) => scoreReadableText(b) - scoreReadableText(a))[0] || htmlToText(cleaned);
-}
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const response = await fetch(EXA_CONTENTS_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": apiKey,
+      },
+      body: JSON.stringify({
+        urls: [requestedUrl.toString()],
+        text: { max_characters: MAX_CONTENT_CHARS },
+      }),
+      signal: controller.signal,
+    });
 
-function htmlToText(html: string) {
-  return decodeEntities(html
-    .replace(/<\/(p|div|section|article|main|h[1-6]|li|blockquote|tr)>/gi, "\n")
-    .replace(/<br\s*\/?>/gi, "\n")
-    .replace(/<[^>]+>/g, " ")
-    .replace(/[ \t]+/g, " ")
-    .replace(/\n{3,}/g, "\n\n")
-    .trim());
-}
+    const raw = await readBoundedText(response, EXA_RESPONSE_BYTES, FETCH_TIMEOUT_MS);
+    if (!response.ok) {
+      throw new Error(`Content extraction failed (${response.status}).`);
+    }
 
-function scoreReadableText(text: string) {
-  const words = text.split(/\s+/).filter(Boolean).length;
-  const paragraphs = text.split(/\n{2,}/).filter((part) => part.trim().split(/\s+/).length >= 12).length;
-  const punctuation = (text.match(/[.!?]/g) || []).length;
-  const navPenalty = (text.match(/\b(cookie|subscribe|sign in|advertisement|privacy policy|all rights reserved)\b/gi) || []).length * 30;
-  return words + paragraphs * 80 + punctuation * 4 - navPenalty;
-}
+    let payload: ExaContentsResponse;
+    try {
+      payload = JSON.parse(raw) as ExaContentsResponse;
+    } catch {
+      throw new Error("Content extraction returned an invalid response.");
+    }
+    if (!Array.isArray(payload.results) || payload.results.length === 0) {
+      throw new Error("This page did not return readable content.");
+    }
 
-const UI_PHRASE_PATTERNS = [
-  /^skip to (?:main )?content\b/i,
-  /^skip to navigation\b/i,
-  /^jump to (?:main )?content\b/i,
-  /^site search\b/i,
-  /^search\.{3}$/i,
-  /^watch live\b/i,
-  /^sign in\b/i,
-  /^sign up\b/i,
-  /^subscribe\b/i,
-  /^accept (?:all )?cookies\b/i,
-  /^manage cookies\b/i,
-  /^cookie (?:settings|policy|preferences)\b/i,
-  /^menu\b/i,
-  /^toggle (?:menu|navigation)\b/i,
-  /^close menu\b/i,
-  /^advertisement\b/i,
-];
+    const result = payload.results[0] as ExaContentsResult;
+    const content = normalizeText(asOptionalString(result.text) || "");
+    if (!content) {
+      throw new Error("This page did not return readable content.");
+    }
 
-function stripLeadingUiPhrases(text: string) {
-  let result = text;
-  let changed = true;
-  while (changed) {
-    changed = false;
-    const trimmed = result.replace(/^[\s\n\r]+/, "");
-    for (const pattern of UI_PHRASE_PATTERNS) {
-      const match = trimmed.match(pattern);
-      if (match) {
-        result = trimmed.slice(match[0].length);
-        changed = true;
-        break;
+    let finalUrl = requestedUrl;
+    const returnedUrl = asOptionalString(result.url);
+    if (returnedUrl) {
+      try {
+        finalUrl = validatePublicHttpUrl(returnedUrl);
+      } catch {
+        // A provider-returned redirect URL is metadata only. If it does not
+        // satisfy our public URL policy, retain the already-validated request URL.
+        finalUrl = requestedUrl;
       }
     }
-    if (!changed && trimmed !== result) {
-      result = trimmed;
-    }
-  }
-  return result;
-}
 
-function normalizeText(text: string) {
-  return stripLeadingUiPhrases(text)
-    .replace(/\r/g, "\n")
-    .replace(/[ \t]+/g, " ")
-    .replace(/\n[ \t]+/g, "\n")
-    .replace(/\n{3,}/g, "\n\n")
-    .trim()
-    .slice(0, MAX_CONTENT_CHARS);
+    return {
+      content,
+      finalUrl,
+      title: asOptionalString(result.title),
+      author: asOptionalString(result.author),
+      publishedDate: asOptionalString(result.publishedDate),
+    };
+  } finally {
+    clearTimeout(timeoutId);
+  }
 }
 
 Deno.serve(async (req) => {
@@ -290,32 +223,17 @@ Deno.serve(async (req) => {
       await logImport(user.id, "error", "bad_request", Date.now() - startedAt);
       return jsonResponse({ error: "Invalid JSON body." }, 400, corsHeaders);
     }
-    const parsedUrl = validatePublicHttpUrl(String(body.url || "").trim());
-    const { response, finalUrl } = await fetchWithTimeout(parsedUrl);
-
-    if (!response.ok) {
-      await logImport(user.id, "error", `upstream_${response.status}`, Date.now() - startedAt);
-      return jsonResponse({ error: `Could not fetch source (${response.status}).` }, 502, corsHeaders);
-    }
-
-    const contentType = response.headers.get("content-type") || "";
-    if (!contentType.includes("text/html") && !contentType.includes("text/plain") && !contentType.includes("application/xhtml+xml")) {
-      await logImport(user.id, "error", "unsupported_type", Date.now() - startedAt);
-      return jsonResponse({ error: "Only HTML and plain text pages can be imported from a URL." }, 415, corsHeaders);
-    }
 
-    const raw = await readBoundedText(response);
-    const isHtml = contentType.includes("html") || /<html|<article|<main|<p[\s>]/i.test(raw);
-    const content = normalizeText(isHtml ? stripHtml(raw) : raw);
+    const requestedUrl = validatePublicHttpUrl(String((body as Record<string, unknown>).url || "").trim());
+    const extracted = await extractViaExa(requestedUrl);
+    const content = extracted.content;
 
     if (content.split(/\s+/).filter(Boolean).length < 20) {
       await logImport(user.id, "error", "too_short", Date.now() - startedAt);
       return jsonResponse({ error: "This page did not contain enough readable text to import." }, 422, corsHeaders);
     }
 
-    const title = isHtml ? getTitle(raw, finalUrl.hostname) : finalUrl.pathname.split("/").pop() || finalUrl.hostname;
-    const author = isHtml ? getMeta(raw, ["author", "article:author"]) : undefined;
-    const publishedDate = isHtml ? getMeta(raw, ["article:published_time", "date", "dc.date", "pubdate"]) : undefined;
+    const title = extracted.title || extracted.finalUrl.pathname.split("/").pop() || extracted.finalUrl.hostname;
     const excerpt = content.slice(0, 220).replace(/\s+\S*$/, "").trim();
 
     await logImport(user.id, "success", undefined, Date.now() - startedAt);
@@ -323,11 +241,11 @@ Deno.serve(async (req) => {
       title,
       content,
       wordCount: content.split(/\s+/).filter(Boolean).length,
-      author,
-      publishedDate,
-      domain: finalUrl.hostname,
+      author: extracted.author,
+      publishedDate: extracted.publishedDate,
+      domain: extracted.finalUrl.hostname,
       excerpt,
-      url: finalUrl.toString(),
+      url: extracted.finalUrl.toString(),
     }, 200, corsHeaders);
   } catch (error) {
     const message = error instanceof Error ? error.message : "Failed to import source.";

From d50514830bc3a82c174ab8801f5b1cc23bde528b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:30:18 +0200
Subject: [PATCH 50/84] security: remove misleading pre-fetch DNS check helper

---
 .../functions/import-source/url-validation.ts | 32 ++++---------------
 1 file changed, 6 insertions(+), 26 deletions(-)

diff --git a/supabase/functions/import-source/url-validation.ts b/supabase/functions/import-source/url-validation.ts
index 13f10b6e4..68ec1a6b5 100644
--- a/supabase/functions/import-source/url-validation.ts
+++ b/supabase/functions/import-source/url-validation.ts
@@ -1,6 +1,9 @@
-// SSRF-safe URL validation helpers for the import-source edge function.
-// Exported separately from index.ts so they can be unit-tested without
-// invoking Deno.serve at module load.
+// URL syntax/literal-address validation helpers for import-source.
+//
+// The importer sends validated URLs as data to a fixed Exa contents endpoint;
+// it does not connect directly to the user-controlled hostname. Literal private
+// addresses are still rejected here as a product/security policy and to avoid
+// asking the extraction provider to process obviously local destinations.
 //
 // isPrivateIpv4/isPrivateIpv6 live in ../_shared/url-validation.ts and are
 // re-exported here so this file and the shared copy can't drift apart.
@@ -37,26 +40,3 @@ export function validatePublicHttpUrl(rawUrl: string): URL {
   parsed.hash = "";
   return parsed;
 }
-
-// Re-checks the hostname's *resolved* addresses, not just its literal text, so a
-// public-looking domain that resolves to a private/link-local IP (DNS rebinding)
-// is still rejected. Call this immediately before every fetch, including redirect hops.
-export async function validateResolvedPublicHost(url: URL): Promise<void> {
-  const hostname = url.hostname.toLowerCase();
-  if (isPrivateIpv4(hostname) || isPrivateIpv6(hostname)) {
-    throw new Error("Private and local network URLs cannot be imported.");
-  }
-
-  const results = await Promise.allSettled([
-    Deno.resolveDns(hostname, "A"),
-    Deno.resolveDns(hostname, "AAAA"),
-  ]);
-  const addresses = results.flatMap((result) => (result.status === "fulfilled" ? result.value : []));
-
-  if (addresses.length === 0) {
-    throw new Error("Could not resolve host.");
-  }
-  if (addresses.some((address) => isPrivateIpv4(address) || isPrivateIpv6(address))) {
-    throw new Error("Private and local network URLs cannot be imported.");
-  }
-}

From db005a588550da88790029eb4f37bbc5a6230f15 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:30:26 +0200
Subject: [PATCH 51/84] test: prevent arbitrary source-import egress regression

---
 src/test/import-source-egress.test.ts | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 src/test/import-source-egress.test.ts

diff --git a/src/test/import-source-egress.test.ts b/src/test/import-source-egress.test.ts
new file mode 100644
index 000000000..2ef31273d
--- /dev/null
+++ b/src/test/import-source-egress.test.ts
@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const source = readFileSync(
+  new URL('../../supabase/functions/import-source/index.ts', import.meta.url),
+  'utf8',
+);
+
+describe('import-source egress boundary', () => {
+  it('uses one fixed Exa network destination rather than fetching the user URL', () => {
+    expect(source).toContain('const EXA_CONTENTS_URL = "https://api.exa.ai/contents"');
+
+    const fetchTargets = [...source.matchAll(/\bfetch\(([^,\n]+)/g)].map((match) => match[1].trim());
+    expect(fetchTargets).toEqual(['EXA_CONTENTS_URL']);
+    expect(source).not.toMatch(/fetch\(\s*(?:requestedUrl|finalUrl|currentUrl|body\.url)/);
+  });
+
+  it('keeps provider response consumption byte- and time-bounded', () => {
+    expect(source).toContain('readBoundedText(response, EXA_RESPONSE_BYTES, FETCH_TIMEOUT_MS)');
+  });
+});

From 927c7e511c667a0de0a38b621d38a2e9ebe01c92 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:31:27 +0200
Subject: [PATCH 52/84] fix: persist preferences without privileged insert

---
 src/lib/stores/settings-store.ts | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/src/lib/stores/settings-store.ts b/src/lib/stores/settings-store.ts
index 4b9b15e81..f3b6249d0 100644
--- a/src/lib/stores/settings-store.ts
+++ b/src/lib/stores/settings-store.ts
@@ -67,7 +67,7 @@ async function getUserId() {
   return data.user?.id || null;
 }
 
-async function upsertSettings(payload: {
+async function persistSettings(payload: {
   language: string;
   output_language: string;
   theme: string;
@@ -76,11 +76,18 @@ async function upsertSettings(payload: {
 }) {
   const userId = await getUserId();
   if (!userId) return;
-  const { error } = await supabase.from('user_settings').upsert({
-    user_id: userId,
-    ...payload,
-    updated_at: new Date().toISOString(),
-  }, { onConflict: 'user_id' });
+
+  // user_settings is provisioned by the auth trigger. Security hardening
+  // intentionally revoked authenticated INSERT/DELETE and permits only selected
+  // preference columns to be updated, so browser persistence must use UPDATE
+  // rather than UPSERT (which requires INSERT privilege even on conflict).
+  const { error } = await supabase
+    .from('user_settings')
+    .update({
+      ...payload,
+      updated_at: new Date().toISOString(),
+    })
+    .eq('user_id', userId);
   if (error) {
     console.warn('[SettingsStore] Failed to persist settings:', error.message);
   }
@@ -99,7 +106,7 @@ export const useSettingsStore = create<SettingsState>()(
       setLanguage: (language) => {
         set({ language });
         void i18n.changeLanguage(language);
-        void upsertSettings({
+        void persistSettings({
           language,
           output_language: get().outputLanguage,
           theme: get().theme,
@@ -109,7 +116,7 @@ export const useSettingsStore = create<SettingsState>()(
       },
       setOutputLanguage: (outputLanguage) => {
         set({ outputLanguage });
-        void upsertSettings({
+        void persistSettings({
           language: get().language,
           output_language: outputLanguage,
           theme: get().theme,
@@ -119,7 +126,7 @@ export const useSettingsStore = create<SettingsState>()(
       },
       setTheme: (theme) => {
         set({ theme });
-        void upsertSettings({
+        void persistSettings({
           language: get().language,
           output_language: get().outputLanguage,
           theme,
@@ -129,7 +136,7 @@ export const useSettingsStore = create<SettingsState>()(
       },
       setSystemPrompt: (prompt) => {
         set({ customSystemPrompt: prompt });
-        void upsertSettings({
+        void persistSettings({
           language: get().language,
           output_language: get().outputLanguage,
           theme: get().theme,
@@ -148,7 +155,7 @@ export const useSettingsStore = create<SettingsState>()(
             [feature]: { ...state.featureConfigs[feature], ...config },
           },
         }));
-        void upsertSettings({
+        void persistSettings({
           language: get().language,
           output_language: get().outputLanguage,
           theme: get().theme,

From 1baac0774b4aa5478587afdae8b5a0d2b97d936b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:31:37 +0200
Subject: [PATCH 53/84] fix: restore output-language preference privilege

---
 ...0827000000_user_settings_output_language_privilege.sql | 8 ++++++++
 1 file changed, 8 insertions(+)
 create mode 100644 supabase/migrations/20260827000000_user_settings_output_language_privilege.sql

diff --git a/supabase/migrations/20260827000000_user_settings_output_language_privilege.sql b/supabase/migrations/20260827000000_user_settings_output_language_privilege.sql
new file mode 100644
index 000000000..8dc2da334
--- /dev/null
+++ b/supabase/migrations/20260827000000_user_settings_output_language_privilege.sql
@@ -0,0 +1,8 @@
+-- Restore the one user-editable preference column omitted from the 2026-08-19
+-- column-level user_settings hardening. Authenticated users still cannot INSERT,
+-- DELETE, or update entitlement/billing fields.
+--
+-- IMPORTANT: this migration is source-only on the current feature branch. It
+-- has not been applied to staging or production.
+
+GRANT UPDATE (output_language) ON public.user_settings TO authenticated;

From f2eabb82749d349e31d44c1f5bd96d04cb3bcb90 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:31:58 +0200
Subject: [PATCH 54/84] test: enforce least-privilege settings persistence

---
 src/test/settings-store.test.ts | 46 +++++++++++++++++++++------------
 1 file changed, 30 insertions(+), 16 deletions(-)

diff --git a/src/test/settings-store.test.ts b/src/test/settings-store.test.ts
index 454abb663..bf70233f3 100644
--- a/src/test/settings-store.test.ts
+++ b/src/test/settings-store.test.ts
@@ -23,17 +23,27 @@ describe("settings-store", () => {
     expect(state.featureConfigs.generate.model).toBe("gemini-3-flash-preview");
     expect(state.featureConfigs.brainstorm.temperature).toBe(0.9);
     expect(state.featureConfigs.factoids.temperature).toBe(0.3);
+    expect(state.featureConfigs.sparring.model).toBe("gemini-3-flash-preview");
+    expect(state.featureConfigs.sparring.temperature).toBe(0.75);
   });
 
-  it("setFeatureConfig merges updates and persists", async () => {
+  it("setFeatureConfig merges updates and persists with UPDATE, not UPSERT", async () => {
     const store = useSettingsStore.getState();
-    store.setFeatureConfig("generate", { temperature: 0.2 });
+    store.setFeatureConfig("sparring", { temperature: 0.2 });
     await new Promise((resolve) => setTimeout(resolve, 0));
-    expect(useSettingsStore.getState().featureConfigs.generate.temperature).toBe(0.2);
+
+    expect(useSettingsStore.getState().featureConfigs.sparring.temperature).toBe(0.2);
     expect(supabaseMock.from).toHaveBeenCalledWith("user_settings");
+    const settingsQuery = supabaseMock.from.mock.results.find(({ value }) => value.update)?.value;
+    expect(settingsQuery.update).toHaveBeenCalledWith(expect.objectContaining({
+      feature_configs: expect.objectContaining({
+        sparring: expect.objectContaining({ temperature: 0.2 }),
+      }),
+    }));
+    expect(settingsQuery.upsert).not.toHaveBeenCalled();
   });
 
-  it("setSystemPrompt updates local state and upserts settings", async () => {
+  it("setSystemPrompt updates local state and updates settings", async () => {
     const store = useSettingsStore.getState();
     store.setSystemPrompt("Custom system");
     await new Promise((resolve) => setTimeout(resolve, 0));
@@ -63,6 +73,7 @@ describe("settings-store", () => {
     expect(state.featureConfigs.generate.provider).toBe("google");
     expect(state.featureConfigs.generate.model).toBe("gemini-3-flash-preview");
     expect(state.featureConfigs.attack.model).toBe("gemini-3-flash-preview");
+    expect(state.featureConfigs.sparring.model).toBe("gemini-3-flash-preview");
   });
 
   it("resetLocalData restores defaults", () => {
@@ -76,6 +87,7 @@ describe("settings-store", () => {
     expect(state.theme).toBe("system");
     expect(state.customSystemPrompt).toBeUndefined();
     expect(state.featureConfigs.generate.model).toBe("gemini-3-flash-preview");
+    expect(state.featureConfigs.sparring.model).toBe("gemini-3-flash-preview");
     expect(state.wikiResearchEnabled).toBe(false);
   });
 
@@ -90,18 +102,17 @@ describe("settings-store", () => {
     store.setTheme("dark");
     await new Promise((resolve) => setTimeout(resolve, 0));
 
-    const settingsQuery = supabaseMock.from.mock.results.find(({ value }) => value.upsert)?.value;
-    expect(settingsQuery.upsert).toHaveBeenCalledWith(
-      expect.any(Object),
-      { onConflict: "user_id" },
-    );
-    expect(settingsQuery.upsert.mock.calls[0][0]).not.toHaveProperty("wiki_research_enabled");
+    const settingsQuery = supabaseMock.from.mock.results.find(({ value }) => value.update)?.value;
+    expect(settingsQuery.update).toHaveBeenCalledWith(expect.any(Object));
+    expect(settingsQuery.update.mock.calls[0][0]).not.toHaveProperty("wiki_research_enabled");
+    expect(settingsQuery.upsert).not.toHaveBeenCalled();
   });
 
   it("reports settings persistence failures", async () => {
     const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const upsert = vi.fn(async () => ({ data: null, error: { message: "database unavailable" } }));
-    supabaseMock.from.mockImplementationOnce((() => ({ upsert })) as never);
+    const eq = vi.fn(async () => ({ data: null, error: { message: "database unavailable" } }));
+    const update = vi.fn(() => ({ eq }));
+    supabaseMock.from.mockImplementationOnce((() => ({ update })) as never);
 
     useSettingsStore.getState().setTheme("dark");
     await new Promise((resolve) => setTimeout(resolve, 0));
@@ -112,12 +123,15 @@ describe("settings-store", () => {
 
   it("getFeatureConfig returns defaults when missing", () => {
     useSettingsStore.setState({ featureConfigs: {} } as Partial<ReturnType<typeof useSettingsStore.getState>>);
-    const config = useSettingsStore.getState().getFeatureConfig("ask");
-    expect(config.provider).toBe("google");
-    expect(config.model).toBe("gemini-3-flash-preview");
+    const askConfig = useSettingsStore.getState().getFeatureConfig("ask");
+    const sparringConfig = useSettingsStore.getState().getFeatureConfig("sparring");
+    expect(askConfig.provider).toBe("google");
+    expect(askConfig.model).toBe("gemini-3-flash-preview");
+    expect(sparringConfig.provider).toBe("google");
+    expect(sparringConfig.temperature).toBe(0.75);
   });
 
-  it("does not upsert when user is not signed in", async () => {
+  it("does not update settings when user is not signed in", async () => {
     setMockAuthUser(null);
     const store = useSettingsStore.getState();
     store.setTheme("dark");

From b7bcb28f82da8d337adbc86ec2e1cb432ade9d57 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:32:48 +0200
Subject: [PATCH 55/84] test: update security invariants for fixed egress

---
 src/test/security-hardening.test.ts | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)

diff --git a/src/test/security-hardening.test.ts b/src/test/security-hardening.test.ts
index 56ffaefae..fc9dc0ca5 100644
--- a/src/test/security-hardening.test.ts
+++ b/src/test/security-hardening.test.ts
@@ -6,6 +6,7 @@ const root = resolve(import.meta.dirname, '../..');
 const read = (path: string) => readFileSync(resolve(root, path), 'utf8');
 const migration = read('supabase/migrations/20260819000000_security_hardening.sql');
 const advisorMigration = read('supabase/migrations/20260820090000_advisor_security_cleanup.sql');
+const outputLanguageMigration = read('supabase/migrations/20260827000000_user_settings_output_language_privilege.sql');
 const ai = read('supabase/functions/ai/index.ts');
 const stream = read('supabase/functions/ai-stream/index.ts');
 const importer = read('supabase/functions/import-source/index.ts');
@@ -17,9 +18,14 @@ describe('security hardening regressions', () => {
   it('makes entitlements and usage ledger service-controlled and fails closed for missing state', () => {
     expect(migration).toContain('REVOKE INSERT, UPDATE, DELETE ON public.user_settings');
     expect(migration).toContain('GRANT UPDATE (language, theme, feature_configs, custom_system_prompt, updated_at)');
+    expect(outputLanguageMigration).toContain('GRANT UPDATE (output_language) ON public.user_settings TO authenticated');
     expect(migration).toContain('REVOKE INSERT, UPDATE, DELETE ON public.ai_requests');
     expect(ai).toContain('if (!user) return { tier: "expired", dailyLimit: 0');
     expect(stream).toContain('if (!user) return { tier: "expired", dailyLimit: 0');
+
+    const settingsStore = read('src/lib/stores/settings-store.ts');
+    expect(settingsStore).toContain(".from('user_settings')\n    .update(");
+    expect(settingsStore).not.toContain(".from('user_settings').upsert");
   });
 
   it('uses one server-only atomic quota reservation from every billable entrypoint', () => {
@@ -28,12 +34,14 @@ describe('security hardening regressions', () => {
     for (const source of [ai, stream, importer]) expect(source).toContain('consume_daily_quota');
     expect(ai).toContain('Unable to verify your quota');
     expect(stream).toContain('Unable to verify your quota');
+    expect(importer).toContain('Unable to verify your quota');
     expect(ai).not.toContain('return { allowed: true }; // Fail open');
     expect(stream).not.toContain('return { allowed: true };\n  } catch');
   });
 
   it('uses code-scoped sharing and disallows anonymous share creation', () => {
     expect(migration).toContain('DROP POLICY IF EXISTS "shared_items_select_public"');
+    expect(migration).toContain('REVOKE ALL ON public.shared_items FROM anon, authenticated');
     expect(migration).toContain('FUNCTION public.get_shared_item(p_share_code text)');
     expect(share).toContain('if (!userId)');
     expect(share).toContain('crypto.getRandomValues');
@@ -56,17 +64,22 @@ describe('security hardening regressions', () => {
     expect(promo).toContain('userClient.rpc("redeem_promo_code_atomic", { p_code: code })');
   });
 
-  it('resolves DNS and bounds importer bodies before processing', () => {
-    expect(importer).toContain('validateResolvedPublicHost(currentUrl)');
-    expect(importer).toContain('readBoundedText(response)');
-    expect(read('supabase/functions/import-source/resource-limits.ts')).toContain('MAX_RESPONSE_BYTES');
+  it('keeps source import behind fixed egress and bounds provider responses', () => {
+    expect(importer).toContain('const EXA_CONTENTS_URL = "https://api.exa.ai/contents"');
+    const fetchTargets = [...importer.matchAll(/\bfetch\(([^,\n]+)/g)].map((match) => match[1].trim());
+    expect(fetchTargets).toEqual(['EXA_CONTENTS_URL']);
+    expect(importer).toContain('readBoundedText(response, EXA_RESPONSE_BYTES, FETCH_TIMEOUT_MS)');
+    const limits = read('supabase/functions/import-source/resource-limits.ts');
+    expect(limits).toContain('MAX_RESPONSE_BYTES');
+    expect(limits).toContain('MAX_RESPONSE_READ_MS');
   });
 
-  it('uses allowlisted model/provider pairs and SSRF-safe citation verification', () => {
+  it('uses allowlisted model/provider pairs and does not fetch model citation URLs', () => {
     expect(ai).toContain('function providerForModel');
     expect(ai).toContain('Unsupported model or provider combination');
-    // SSRF-safe verification now lives in the shared research module.
-    expect(read('supabase/functions/_shared/research.ts')).toContain('Do not fetch model-provided citation URLs');
+    const research = read('supabase/functions/_shared/research.ts');
+    expect(research).toContain('Do not fetch model-provided citation URLs');
+    expect(research).toContain('return false;');
     expect(ai).not.toContain('fetchWithTimeout(currentUrl.toString(), { method: "HEAD"');
   });
 

From 0887417ae908f8cff645c2accbee7ba04f11f3cb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:33:17 +0200
Subject: [PATCH 56/84] fix: scope atomic daily counters by workload

---
 ...60827001000_scope_daily_usage_counters.sql | 60 +++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 supabase/migrations/20260827001000_scope_daily_usage_counters.sql

diff --git a/supabase/migrations/20260827001000_scope_daily_usage_counters.sql b/supabase/migrations/20260827001000_scope_daily_usage_counters.sql
new file mode 100644
index 000000000..558d54b3d
--- /dev/null
+++ b/supabase/migrations/20260827001000_scope_daily_usage_counters.sql
@@ -0,0 +1,60 @@
+-- Separate independently configured daily quotas while keeping one atomic RPC.
+-- Existing AI callers omit p_quota_key and therefore use the default 'ai'.
+-- import-source passes 'import_source' so URL imports cannot consume a user's
+-- normal AI allowance (or vice versa).
+--
+-- IMPORTANT: this migration is source-only on the current feature branch. It
+-- has not been applied to staging or production.
+
+ALTER TABLE public.daily_usage_counters
+  ADD COLUMN IF NOT EXISTS quota_key text NOT NULL DEFAULT 'ai';
+
+ALTER TABLE public.daily_usage_counters
+  DROP CONSTRAINT IF EXISTS daily_usage_counters_pkey;
+
+ALTER TABLE public.daily_usage_counters
+  ADD CONSTRAINT daily_usage_counters_pkey PRIMARY KEY (user_id, usage_date, quota_key);
+
+DROP FUNCTION IF EXISTS public.consume_daily_quota(uuid, integer);
+
+CREATE OR REPLACE FUNCTION public.consume_daily_quota(
+  p_user_id uuid,
+  p_limit integer,
+  p_quota_key text DEFAULT 'ai'
+)
+RETURNS TABLE (allowed boolean, current_count integer)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_quota_key text := nullif(trim(p_quota_key), '');
+BEGIN
+  IF auth.role() <> 'service_role' OR p_user_id IS NULL OR p_limit < 1 OR v_quota_key IS NULL THEN
+    RAISE EXCEPTION 'quota reservation is restricted to trusted server code';
+  END IF;
+
+  RETURN QUERY
+  WITH reserved AS (
+    INSERT INTO public.daily_usage_counters (user_id, usage_date, quota_key, request_count)
+    VALUES (p_user_id, CURRENT_DATE, v_quota_key, 1)
+    ON CONFLICT (user_id, usage_date, quota_key) DO UPDATE
+      SET request_count = public.daily_usage_counters.request_count + 1
+      WHERE public.daily_usage_counters.request_count < p_limit
+    RETURNING request_count
+  )
+  SELECT true, request_count FROM reserved
+  UNION ALL
+  SELECT false, COALESCE((
+    SELECT request_count
+    FROM public.daily_usage_counters
+    WHERE user_id = p_user_id
+      AND usage_date = CURRENT_DATE
+      AND quota_key = v_quota_key
+  ), 0)
+  WHERE NOT EXISTS (SELECT 1 FROM reserved);
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.consume_daily_quota(uuid, integer, text) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.consume_daily_quota(uuid, integer, text) TO service_role;

From 64d699150b916a1a6f94550defe43d1e780c080f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:33:46 +0200
Subject: [PATCH 57/84] fix: isolate source-import quota reservations

---
 supabase/functions/import-source/index.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/supabase/functions/import-source/index.ts b/supabase/functions/import-source/index.ts
index 4434d9170..a1fcb33a3 100644
--- a/supabase/functions/import-source/index.ts
+++ b/supabase/functions/import-source/index.ts
@@ -65,6 +65,7 @@ async function consumeDailyImportQuota(userId: string): Promise<{ allowed: boole
   const { data, error } = await supabase.rpc("consume_daily_quota", {
     p_user_id: userId,
     p_limit: DAILY_IMPORT_LIMIT,
+    p_quota_key: "import_source",
   });
   if (error) throw error;
   const row = Array.isArray(data) ? data[0] : data;

From db1cb9d4240414569a24cf7a889dd68c4271584f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:34:23 +0200
Subject: [PATCH 58/84] test: match executable fetch calls only

---
 src/test/import-source-egress.test.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/test/import-source-egress.test.ts b/src/test/import-source-egress.test.ts
index 2ef31273d..d3356f14b 100644
--- a/src/test/import-source-egress.test.ts
+++ b/src/test/import-source-egress.test.ts
@@ -10,9 +10,9 @@ describe('import-source egress boundary', () => {
   it('uses one fixed Exa network destination rather than fetching the user URL', () => {
     expect(source).toContain('const EXA_CONTENTS_URL = "https://api.exa.ai/contents"');
 
-    const fetchTargets = [...source.matchAll(/\bfetch\(([^,\n]+)/g)].map((match) => match[1].trim());
+    const fetchTargets = [...source.matchAll(/\bawait\s+fetch\(([^,\n]+)/g)].map((match) => match[1].trim());
     expect(fetchTargets).toEqual(['EXA_CONTENTS_URL']);
-    expect(source).not.toMatch(/fetch\(\s*(?:requestedUrl|finalUrl|currentUrl|body\.url)/);
+    expect(source).not.toMatch(/await\s+fetch\(\s*(?:requestedUrl|finalUrl|currentUrl|body\.url)/);
   });
 
   it('keeps provider response consumption byte- and time-bounded', () => {

From e812a42c2717460bd919eb9fd69ca5beeaacabef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:34:42 +0200
Subject: [PATCH 59/84] test: match executable importer fetch calls only

---
 src/test/security-hardening.test.ts | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/test/security-hardening.test.ts b/src/test/security-hardening.test.ts
index fc9dc0ca5..7edd1b7d6 100644
--- a/src/test/security-hardening.test.ts
+++ b/src/test/security-hardening.test.ts
@@ -7,6 +7,7 @@ const read = (path: string) => readFileSync(resolve(root, path), 'utf8');
 const migration = read('supabase/migrations/20260819000000_security_hardening.sql');
 const advisorMigration = read('supabase/migrations/20260820090000_advisor_security_cleanup.sql');
 const outputLanguageMigration = read('supabase/migrations/20260827000000_user_settings_output_language_privilege.sql');
+const quotaScopeMigration = read('supabase/migrations/20260827001000_scope_daily_usage_counters.sql');
 const ai = read('supabase/functions/ai/index.ts');
 const stream = read('supabase/functions/ai-stream/index.ts');
 const importer = read('supabase/functions/import-source/index.ts');
@@ -28,7 +29,7 @@ describe('security hardening regressions', () => {
     expect(settingsStore).not.toContain(".from('user_settings').upsert");
   });
 
-  it('uses one server-only atomic quota reservation from every billable entrypoint', () => {
+  it('uses atomic quota reservations and separates independently configured workloads', () => {
     expect(migration).toContain('ON CONFLICT (user_id, usage_date) DO UPDATE');
     expect(migration).toContain("auth.role() <> 'service_role'");
     for (const source of [ai, stream, importer]) expect(source).toContain('consume_daily_quota');
@@ -37,6 +38,10 @@ describe('security hardening regressions', () => {
     expect(importer).toContain('Unable to verify your quota');
     expect(ai).not.toContain('return { allowed: true }; // Fail open');
     expect(stream).not.toContain('return { allowed: true };\n  } catch');
+
+    expect(quotaScopeMigration).toContain('PRIMARY KEY (user_id, usage_date, quota_key)');
+    expect(quotaScopeMigration).toContain("p_quota_key text DEFAULT 'ai'");
+    expect(importer).toContain('p_quota_key: "import_source"');
   });
 
   it('uses code-scoped sharing and disallows anonymous share creation', () => {
@@ -66,7 +71,7 @@ describe('security hardening regressions', () => {
 
   it('keeps source import behind fixed egress and bounds provider responses', () => {
     expect(importer).toContain('const EXA_CONTENTS_URL = "https://api.exa.ai/contents"');
-    const fetchTargets = [...importer.matchAll(/\bfetch\(([^,\n]+)/g)].map((match) => match[1].trim());
+    const fetchTargets = [...importer.matchAll(/\bawait\s+fetch\(([^,\n]+)/g)].map((match) => match[1].trim());
     expect(fetchTargets).toEqual(['EXA_CONTENTS_URL']);
     expect(importer).toContain('readBoundedText(response, EXA_RESPONSE_BYTES, FETCH_TIMEOUT_MS)');
     const limits = read('supabase/functions/import-source/resource-limits.ts');

From 29c72d824ae3e2892b1cd7a3820127f9a168c02b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:35:30 +0200
Subject: [PATCH 60/84] test: isolate and cover sparring output language

---
 src/test/ai/sparring-client.test.ts | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/src/test/ai/sparring-client.test.ts b/src/test/ai/sparring-client.test.ts
index 03f1a5322..96aa17157 100644
--- a/src/test/ai/sparring-client.test.ts
+++ b/src/test/ai/sparring-client.test.ts
@@ -1,5 +1,9 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+const { settingsState } = vi.hoisted(() => ({
+  settingsState: { outputLanguage: 'en' as 'en' | 'es' | 'hu' },
+}));
+
 vi.mock('@/lib/ai/client', () => ({
   AIResponseError: class AIResponseError extends Error {
     details?: Record<string, unknown>;
@@ -12,6 +16,12 @@ vi.mock('@/lib/ai/client', () => ({
   askChat: vi.fn(),
 }));
 
+vi.mock('@/lib/stores/settings-store', () => ({
+  useSettingsStore: {
+    getState: () => settingsState,
+  },
+}));
+
 import { askChat } from '@/lib/ai/client';
 import { requestSparringOpponent, requestSparringScorecard } from '@/lib/ai/sparring-client';
 import type { SparringSession } from '@/lib/ai/schemas/sparring';
@@ -65,7 +75,10 @@ const scorecard = {
 };
 
 describe('sparring-client', () => {
-  beforeEach(() => vi.clearAllMocks());
+  beforeEach(() => {
+    vi.clearAllMocks();
+    settingsState.outputLanguage = 'en';
+  });
 
   it('parses a structured opponent response from Ask', async () => {
     vi.mocked(askChat).mockResolvedValueOnce(askOutput(JSON.stringify({
@@ -79,6 +92,19 @@ describe('sparring-client', () => {
     expect(vi.mocked(askChat).mock.calls[0][0]).toContain('Respond to the user\'s actual arguments');
   });
 
+  it('propagates the configured output language into opponent and scorecard prompts', async () => {
+    settingsState.outputLanguage = 'es';
+    vi.mocked(askChat)
+      .mockResolvedValueOnce(askOutput(JSON.stringify({ speech: 'Respuesta del oponente.', pressurePoints: [] })) as never)
+      .mockResolvedValueOnce(askOutput(JSON.stringify(scorecard)) as never);
+
+    await requestSparringOpponent(session, session.turns[2].content, config);
+    await requestSparringScorecard(session, config);
+
+    expect(vi.mocked(askChat).mock.calls[0][0]).toContain('Response language: Spanish (es)');
+    expect(vi.mocked(askChat).mock.calls[1][0]).toContain('Response language: Spanish (es)');
+  });
+
   it('keeps useful plain-text opponent output instead of discarding it', async () => {
     vi.mocked(askChat).mockResolvedValueOnce(askOutput('You never answered why a narrower rule cannot solve the same harm.') as never);
     const result = await requestSparringOpponent(session, session.turns[2].content, config);

From 6093cb92662fb9c89109e4dd8a4049a8e30575d2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:38:31 +0200
Subject: [PATCH 61/84] feat: model Exa search filters as request fields

---
 supabase/functions/_shared/source-quality.ts | 119 ++++++++++++++-----
 1 file changed, 88 insertions(+), 31 deletions(-)

diff --git a/supabase/functions/_shared/source-quality.ts b/supabase/functions/_shared/source-quality.ts
index a628b71aa..965ed6e93 100644
--- a/supabase/functions/_shared/source-quality.ts
+++ b/supabase/functions/_shared/source-quality.ts
@@ -25,6 +25,14 @@ export type ResearchSource = {
   qualityLabel: "strong" | "moderate" | "weak";
 };
 
+export type ExaSearchCategory = "research paper" | "news";
+
+export type SearchRequest = {
+  query: string;
+  includeDomains?: string[];
+  category?: ExaSearchCategory;
+};
+
 const WEAK_DOMAINS = [
   "youtube.com",
   "youtu.be",
@@ -39,6 +47,37 @@ const WEAK_DOMAINS = [
   "medium.com",
 ];
 
+// Exa includeDomains accepts concrete domains rather than TLD wildcards. This
+// list intentionally covers high-value public-sector and intergovernmental
+// sources while search falls back to an unfiltered request if it returns no
+// results, preserving recall for agencies not represented here.
+export const GOVERNMENT_SEARCH_DOMAINS = [
+  "usa.gov",
+  "congress.gov",
+  "census.gov",
+  "bls.gov",
+  "bea.gov",
+  "energy.gov",
+  "epa.gov",
+  "cdc.gov",
+  "nih.gov",
+  "justice.gov",
+  "federalregister.gov",
+  "gov.uk",
+  "canada.ca",
+  "gc.ca",
+  "gov.au",
+  "abs.gov.au",
+  "europa.eu",
+  "ec.europa.eu",
+  "eurostat.ec.europa.eu",
+  "oecd.org",
+  "worldbank.org",
+  "imf.org",
+  "un.org",
+  "who.int",
+];
+
 const RESULTS_PATTERNS = [
   /\btab\b/i,
   /\btabs\b/i,
@@ -205,54 +244,72 @@ export function rankSearchResults(
     });
 }
 
-export function buildSearchQueries(claim: string, region = "", preferredSourceType = "any", timeframe = ""): string[] {
+function dedupeSearchRequests(requests: SearchRequest[]): SearchRequest[] {
+  const accepted: SearchRequest[] = [];
+  for (const request of requests) {
+    const qTokens = new Set(request.query.toLowerCase().split(/\s+/));
+    const isDuplicate = accepted.some((existing) => {
+      const existingTokens = new Set(existing.query.toLowerCase().split(/\s+/));
+      const intersection = [...qTokens].filter((token) => existingTokens.has(token)).length;
+      const smaller = Math.min(qTokens.size, existingTokens.size);
+      const sameFilter = JSON.stringify(existing.includeDomains || []) === JSON.stringify(request.includeDomains || []) && existing.category === request.category;
+      return sameFilter && smaller > 0 && intersection / smaller > 0.85;
+    });
+    if (!isDuplicate) accepted.push(request);
+  }
+  return accepted.slice(0, 6);
+}
+
+/**
+ * Builds Exa search requests with filters represented as request fields rather
+ * than query-operator text. This matches Exa's current API contract:
+ * includeDomains for domain restrictions and category for news/research-paper
+ * verticals. Callers may retry an unfiltered request if a filter returns zero.
+ */
+export function buildSearchRequests(claim: string, region = "", preferredSourceType = "any", timeframe = ""): SearchRequest[] {
   const base = `${claim} ${region}`.trim().replace(/\s+/g, " ");
   const years = timeframe || (/\b202[0-9]\b/.test(base) ? "" : "2025 2026");
-  const queries: string[] = [];
+  const requests: SearchRequest[] = [];
 
-  // Topic-specific queries first (highest priority)
   if (OFFICIAL_DEBATE_PATTERNS.some((pattern) => pattern.test(base)) || /\bdebate|debating\b/i.test(base)) {
-    queries.push(`${base} tab results official`.trim());
-    queries.push(`${base} Tabbycat Calicotab results`.trim());
+    requests.push({ query: `${base} tab results official`.trim() });
+    requests.push({ query: `${base} Tabbycat Calicotab results`.trim() });
   }
 
   if (POLICY_STAT_PATTERNS.some((pattern) => pattern.test(base))) {
-    queries.push(`${base} World Bank OECD IMF UN data ${years}`.trim());
-    queries.push(`${base} government statistics report ${years}`.trim());
+    requests.push({ query: `${base} World Bank OECD IMF UN data ${years}`.trim() });
+    requests.push({ query: `${base} government statistics report ${years}`.trim() });
   }
 
   if (LEGAL_CURRENT_PATTERNS.some((pattern) => pattern.test(base))) {
-    queries.push(`${base} official law court ruling ${years}`.trim());
-    queries.push(`${base} primary source legislation regulation ${years}`.trim());
+    requests.push({ query: `${base} official law court ruling ${years}`.trim() });
+    requests.push({ query: `${base} primary source legislation regulation ${years}`.trim() });
   }
 
-  // Preferred source type queries
-  if (preferredSourceType === "government") queries.push(`${base} site:gov ${years}`.trim());
-  if (preferredSourceType === "academic") queries.push(`${base} study journal university ${years}`.trim());
-  if (preferredSourceType === "news") queries.push(`${base} Reuters AP BBC report ${years}`.trim());
-
-  // General fallback queries
-  queries.push(`${base} official data evidence ${years}`.trim());
-  queries.push(`${base} statistics report study ${years}`.trim());
-
-  // Deduplicate by token overlap: skip when more than 85% of the smaller query's tokens already appear in an accepted query
-  const deduplicated: string[] = [];
-  for (const q of queries) {
-    const qTokens = new Set(q.toLowerCase().split(/\s+/));
-    const isDuplicate = deduplicated.some((existing) => {
-      const existingTokens = new Set(existing.toLowerCase().split(/\s+/));
-      const intersection = [...qTokens].filter((t) => existingTokens.has(t)).length;
-      const smaller = Math.min(qTokens.size, existingTokens.size);
-      return smaller > 0 && intersection / smaller > 0.85;
+  if (preferredSourceType === "government") {
+    requests.push({
+      query: `${base} official government data ${years}`.trim(),
+      includeDomains: GOVERNMENT_SEARCH_DOMAINS,
     });
-    if (!isDuplicate) deduplicated.push(q);
+  }
+  if (preferredSourceType === "academic") {
+    requests.push({ query: `${base} study evidence ${years}`.trim(), category: "research paper" });
+  }
+  if (preferredSourceType === "news") {
+    requests.push({ query: `${base} report ${years}`.trim(), category: "news" });
   }
 
-  return deduplicated.slice(0, 6);
+  requests.push({ query: `${base} official data evidence ${years}`.trim() });
+  requests.push({ query: `${base} statistics report study ${years}`.trim() });
+
+  return dedupeSearchRequests(requests);
+}
+
+/** Backward-compatible helper for callers/tests that need query text only. */
+export function buildSearchQueries(claim: string, region = "", preferredSourceType = "any", timeframe = ""): string[] {
+  return buildSearchRequests(claim, region, preferredSourceType, timeframe).map((request) => request.query);
 }
 
-// Bounded per-result snippet: Exa may return up to 10k characters per result,
-// which would bloat prompts when several results are included.
 const MAX_RESULT_SNIPPET_CHARS = 1200;
 
 export function formatRankedSearchResults(results: RankedSearchResult[]): string {

From 9966b715b798b8d249d1bf3869f0c39bb6ad1d4e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:40:16 +0200
Subject: [PATCH 62/84] feat: use Exa domain and category filters

---
 supabase/functions/_shared/research.ts | 65 ++++++++++++++++++++------
 1 file changed, 51 insertions(+), 14 deletions(-)

diff --git a/supabase/functions/_shared/research.ts b/supabase/functions/_shared/research.ts
index 8e338294a..e21d5715a 100644
--- a/supabase/functions/_shared/research.ts
+++ b/supabase/functions/_shared/research.ts
@@ -4,13 +4,16 @@
 // and free of provider-specific code.
 
 import {
-  buildSearchQueries,
+  buildSearchRequests,
   formatRankedSearchResults,
+  GOVERNMENT_SEARCH_DOMAINS,
   rankSearchResults,
   sourceTitleFromUrl,
   type ExaResult,
+  type ExaSearchCategory,
   type RankedSearchResult,
   type ResearchSource,
+  type SearchRequest,
 } from "./source-quality.ts";
 
 export type { ExaResult, RankedSearchResult, ResearchSource };
@@ -145,8 +148,18 @@ export async function fetchJsonWithTimeout<T = unknown>(
 
 // ============== EXA FUNCTIONS ==============
 
-// exaSearch: web search using Exa's neural search (type "auto" = balanced relevance & speed)
-export async function exaSearch(query: string, signal?: AbortSignal): Promise<ExaResult[]> {
+type ExaSearchOptions = {
+  includeDomains?: string[];
+  category?: ExaSearchCategory;
+};
+
+// Exa's current API exposes includeDomains/category as first-class fields.
+// Keep query text about the topic itself instead of embedding site: operators.
+export async function exaSearch(
+  query: string,
+  signal?: AbortSignal,
+  options: ExaSearchOptions = {},
+): Promise<ExaResult[]> {
   const apiKey = Deno.env.get("EXA_API_KEY");
   if (!apiKey) {
     console.warn("[EXA] EXA_API_KEY not configured");
@@ -160,8 +173,10 @@ export async function exaSearch(query: string, signal?: AbortSignal): Promise<Ex
       body: JSON.stringify({
         query,
         type: "auto",
-        num_results: 10,
-        contents: { text: { max_characters: 10000 } },
+        numResults: 10,
+        ...(options.includeDomains?.length ? { includeDomains: options.includeDomains } : {}),
+        ...(options.category ? { category: options.category } : {}),
+        contents: { text: { maxCharacters: 10000 } },
       }),
     }, 30000, signal);
     throwIfAborted(signal);
@@ -183,6 +198,27 @@ export async function exaSearch(query: string, signal?: AbortSignal): Promise<Ex
   }
 }
 
+async function exaSearchWithFallback(request: SearchRequest, signal?: AbortSignal): Promise<ExaResult[]> {
+  const hasFilter = Boolean(request.category || request.includeDomains?.length);
+  const filtered = await exaSearch(request.query, signal, {
+    includeDomains: request.includeDomains,
+    category: request.category,
+  });
+  if (filtered.length > 0 || !hasFilter) return filtered;
+
+  console.warn(`[EXA] Filtered search returned no results; retrying without filters: ${request.query}`);
+  return exaSearch(request.query, signal);
+}
+
+function preferredFollowUpRequest(query: string, preferredSourceType: string): SearchRequest {
+  if (preferredSourceType === "government") {
+    return { query, includeDomains: GOVERNMENT_SEARCH_DOMAINS };
+  }
+  if (preferredSourceType === "academic") return { query, category: "research paper" };
+  if (preferredSourceType === "news") return { query, category: "news" };
+  return { query };
+}
+
 // exaGetContents: extract full text from a specific URL using Exa's /contents endpoint
 export async function exaGetContents(url: string, signal?: AbortSignal): Promise<string> {
   const apiKey = Deno.env.get("EXA_API_KEY");
@@ -195,7 +231,7 @@ export async function exaGetContents(url: string, signal?: AbortSignal): Promise
     const { response, data } = await fetchJsonWithTimeout<{ results?: unknown }>("https://api.exa.ai/contents", {
       method: "POST",
       headers: { "Content-Type": "application/json", "x-api-key": apiKey },
-      body: JSON.stringify({ urls: [url], text: { max_characters: 8000 } }),
+      body: JSON.stringify({ urls: [url], text: { maxCharacters: 8000 } }),
     }, 30000, signal);
     throwIfAborted(signal);
     if (!response.ok) {
@@ -325,21 +361,21 @@ async function deepResearchInner(
   console.log(`[RESEARCH] Starting (mode: ${options.maxFollowUpQueries > 0 ? "deep" : "light"}) for: ${claim}`);
 
   const preferredSourceType = options.preferredSourceType || "any";
-  const seedQueries = buildSearchQueries(claim, region, preferredSourceType, options.timeframe).slice(0, options.maxSeedQueries);
+  const seedRequests = buildSearchRequests(claim, region, preferredSourceType, options.timeframe).slice(0, options.maxSeedQueries);
   const allResults: Array<ExaResult & { query: string }> = [];
   const matchesPreferredSourceType = (result: RankedSearchResult) => (
     preferredSourceType === "any" ||
     result.sourceType === preferredSourceType
   );
 
-  const seedResults = await Promise.all(seedQueries.map(async (query) => {
-    const results = await exaSearch(query, signal);
+  const seedResults = await Promise.all(seedRequests.map(async (request) => {
+    const results = await exaSearchWithFallback(request, signal);
     throwIfAborted(signal);
-    const ranked = rankSearchResults(results.map((result) => ({ ...result, query })), claim, preferredSourceType);
+    const ranked = rankSearchResults(results.map((result) => ({ ...result, query: request.query })), claim, preferredSourceType);
     const visibleRanked = preferredSourceType === "any" ? ranked : ranked.filter(matchesPreferredSourceType);
-    context.searches.push({ query, results: formatRankedSearchResults(visibleRanked) });
-    console.log(`[RESEARCH] Seed query "${query}": ${results.length} results`);
-    return results.map((result) => ({ ...result, query }));
+    context.searches.push({ query: request.query, results: formatRankedSearchResults(visibleRanked) });
+    console.log(`[RESEARCH] Seed query "${request.query}": ${results.length} results`);
+    return results.map((result) => ({ ...result, query: request.query }));
   }));
   seedResults.forEach((results) => allResults.push(...results));
 
@@ -353,7 +389,8 @@ async function deepResearchInner(
     console.log(`[RESEARCH] Follow-up queries: ${followUpQueries.join(", ")}`);
 
     const followUpPromises = followUpQueries.slice(0, options.maxFollowUpQueries).map(async (query) => {
-      const results = await exaSearch(query, signal);
+      const request = preferredFollowUpRequest(query, preferredSourceType);
+      const results = await exaSearchWithFallback(request, signal);
       throwIfAborted(signal);
       const ranked = rankSearchResults(results.map((result) => ({ ...result, query })), claim, preferredSourceType);
       const visibleRanked = preferredSourceType === "any" ? ranked : ranked.filter(matchesPreferredSourceType);

From 0414e29ab49eb94e969def0cb5a05d08c9e64dc4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:40:52 +0200
Subject: [PATCH 63/84] test: cover first-class Exa source filters

---
 supabase/functions/ai/source-quality.test.ts | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/supabase/functions/ai/source-quality.test.ts b/supabase/functions/ai/source-quality.test.ts
index 936c7f23d..d425b516a 100644
--- a/supabase/functions/ai/source-quality.test.ts
+++ b/supabase/functions/ai/source-quality.test.ts
@@ -1,4 +1,4 @@
-import { buildSearchQueries, rankSearchResults } from "../_shared/source-quality.ts";
+import { buildSearchQueries, buildSearchRequests, GOVERNMENT_SEARCH_DOMAINS, rankSearchResults } from "../_shared/source-quality.ts";
 
 function assert(condition: boolean, message: string) {
   if (!condition) throw new Error(message);
@@ -44,7 +44,7 @@ Deno.test("source ranking respects requested government source type", () => {
       title: "Energy cost data",
       url: "https://www.energy.gov/eere/solar/solar-energy-cost-data",
       content: "Official government data about solar energy costs and electricity generation",
-      query: "solar cheaper than coal site:gov",
+      query: "solar cheaper than coal official government data",
     },
   ], "solar cheaper than coal United States", "government");
 
@@ -68,3 +68,19 @@ Deno.test("search query builder adds legal primary-source queries", () => {
   assert(queries.some((query) => /official law court/i.test(query)), `Expected official legal source query, got ${queries.join("; ")}`);
   assert(queries.some((query) => /primary source/i.test(query)), `Expected primary source query, got ${queries.join("; ")}`);
 });
+
+Deno.test("government preference uses Exa includeDomains instead of site query syntax", () => {
+  const requests = buildSearchRequests("solar energy costs", "United States", "government", "2025 2026");
+  const filtered = requests.find((request) => request.includeDomains?.length);
+  assert(Boolean(filtered), `Expected a domain-filtered government request, got ${JSON.stringify(requests)}`);
+  assert(filtered!.includeDomains!.includes("energy.gov"), "Expected energy.gov in government domain set");
+  assert(filtered!.includeDomains === GOVERNMENT_SEARCH_DOMAINS, "Expected canonical government domain list");
+  assert(requests.every((request) => !/\bsite:/i.test(request.query)), "site: operator must not leak into Exa query text");
+});
+
+Deno.test("academic and news preferences use Exa category fields", () => {
+  const academic = buildSearchRequests("carbon pricing effectiveness", "", "academic");
+  const news = buildSearchRequests("current carbon pricing policy", "", "news");
+  assert(academic.some((request) => request.category === "research paper"), "Expected research paper category");
+  assert(news.some((request) => request.category === "news"), "Expected news category");
+});

From 15357624565ee00c7dbedcb402202e18d3a788ca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:41:15 +0200
Subject: [PATCH 64/84] test: verify Exa filter request bodies and fallback

---
 .../_shared/research-exa-filters.test.ts      | 93 +++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 supabase/functions/_shared/research-exa-filters.test.ts

diff --git a/supabase/functions/_shared/research-exa-filters.test.ts b/supabase/functions/_shared/research-exa-filters.test.ts
new file mode 100644
index 000000000..cce526e31
--- /dev/null
+++ b/supabase/functions/_shared/research-exa-filters.test.ts
@@ -0,0 +1,93 @@
+import { deepResearch, exaSearch } from './research.ts';
+import { GOVERNMENT_SEARCH_DOMAINS } from './source-quality.ts';
+
+function assert(condition: boolean, message: string) {
+  if (!condition) throw new Error(message);
+}
+
+Deno.test('exaSearch sends documented includeDomains/category request fields', async () => {
+  const previousApiKey = Deno.env.get('EXA_API_KEY');
+  const originalFetch = globalThis.fetch;
+  const bodies: Array<Record<string, unknown>> = [];
+  Deno.env.set('EXA_API_KEY', 'test-key');
+
+  globalThis.fetch = (async (_input: Request | URL | string, init?: RequestInit) => {
+    bodies.push(JSON.parse(String(init?.body || '{}')) as Record<string, unknown>);
+    return new Response(JSON.stringify({ results: [] }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  }) as typeof fetch;
+
+  try {
+    await exaSearch('energy reliability data', undefined, {
+      includeDomains: ['energy.gov'],
+      category: 'news',
+    });
+
+    const body = bodies[0];
+    assert(body.query === 'energy reliability data', 'query missing');
+    assert(body.numResults === 10, `Expected numResults=10, got ${String(body.numResults)}`);
+    assert(Array.isArray(body.includeDomains) && body.includeDomains[0] === 'energy.gov', 'includeDomains missing');
+    assert(body.category === 'news', 'category missing');
+    assert(!('num_results' in body), 'legacy num_results field should not be sent');
+    const contents = body.contents as { text?: { maxCharacters?: number; max_characters?: number } };
+    assert(contents?.text?.maxCharacters === 10000, 'text.maxCharacters missing');
+    assert(contents?.text?.max_characters === undefined, 'legacy max_characters should not be sent');
+  } finally {
+    globalThis.fetch = originalFetch;
+    if (previousApiKey === undefined) Deno.env.delete('EXA_API_KEY');
+    else Deno.env.set('EXA_API_KEY', previousApiKey);
+  }
+});
+
+Deno.test('government filtered search retries unfiltered when the domain filter has zero recall', async () => {
+  const previousApiKey = Deno.env.get('EXA_API_KEY');
+  const originalFetch = globalThis.fetch;
+  const bodies: Array<Record<string, unknown>> = [];
+  Deno.env.set('EXA_API_KEY', 'test-key');
+
+  globalThis.fetch = (async (input: Request | URL | string, init?: RequestInit) => {
+    const url = String(input);
+    if (!url.includes('/search')) throw new Error(`Unexpected network target: ${url}`);
+    const body = JSON.parse(String(init?.body || '{}')) as Record<string, unknown>;
+    bodies.push(body);
+    const filtered = Array.isArray(body.includeDomains);
+    return new Response(JSON.stringify({
+      results: filtered ? [] : [{
+        title: 'Federal procurement guidance',
+        url: 'https://www.gsa.gov/policy-regulations/procurement-policy',
+        text: 'Official federal procurement guidance with enough detail to rank as a government source.',
+      }],
+    }), { status: 200, headers: { 'content-type': 'application/json' } });
+  }) as typeof fetch;
+
+  try {
+    const result = await deepResearch(
+      'federal procurement reform',
+      'United States',
+      {
+        provider: 'google',
+        model: 'test-model',
+        callModel: async () => ({ output: { queries: [] } }),
+      },
+      {
+        maxFollowUpQueries: 0,
+        maxUrlsToRead: 0,
+        maxSeedQueries: 1,
+        overallTimeoutMs: 1000,
+        preferredSourceType: 'government',
+      },
+    );
+
+    assert(bodies.length === 2, `Expected filtered request + unfiltered fallback, got ${bodies.length}`);
+    assert(Array.isArray(bodies[0].includeDomains), 'first request should use includeDomains');
+    assert((bodies[0].includeDomains as string[]).length === GOVERNMENT_SEARCH_DOMAINS.length, 'government filter list drifted');
+    assert(bodies[1].includeDomains === undefined, 'fallback must remove the domain filter');
+    assert(result.rankedResults.some((item) => item.url?.includes('gsa.gov')), 'fallback result was not retained');
+  } finally {
+    globalThis.fetch = originalFetch;
+    if (previousApiKey === undefined) Deno.env.delete('EXA_API_KEY');
+    else Deno.env.set('EXA_API_KEY', previousApiKey);
+  }
+});

From 87f4cb158f60a1c5f7ea6efc9f5d9f6505d6b9c7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:43:40 +0200
Subject: [PATCH 65/84] feat: preserve Factoids consulted-source provenance

---
 src/lib/ai/client.ts | 158 ++++++++-----------------------------------
 1 file changed, 28 insertions(+), 130 deletions(-)

diff --git a/src/lib/ai/client.ts b/src/lib/ai/client.ts
index df883b92c..a34153afe 100644
--- a/src/lib/ai/client.ts
+++ b/src/lib/ai/client.ts
@@ -71,9 +71,7 @@ function parseDiscoveredSources(value: unknown): DiscoveredSource[] {
 // Enable debug logging in development
 const DEBUG = import.meta.env.DEV;
 
-/**
- * Base class for AI-related errors with structured information.
- */
+/** Base class for AI-related errors with structured information. */
 export class AIError extends Error {
   readonly statusCode?: number;
   readonly requestId?: string;
@@ -91,10 +89,6 @@ export class AIError extends Error {
   }
 }
 
-/**
- * Error for authentication failures (401/403).
- * User should re-authenticate.
- */
 export class AIAuthError extends AIError {
   constructor(message: string = 'Authentication required. Please sign in again.', options?: { statusCode?: number; requestId?: string }) {
     super(message, options);
@@ -102,9 +96,6 @@ export class AIAuthError extends AIError {
   }
 }
 
-/**
- * Error for rate limit exceeded (429).
- */
 export class AIRateLimitError extends AIError {
   readonly limit?: number;
   readonly current?: number;
@@ -122,9 +113,6 @@ export class AIRateLimitError extends AIError {
   }
 }
 
-/**
- * Error for subscription limit reached (402) or trial expired.
- */
 export class AISubscriptionError extends AIError {
   readonly code?: string;
   readonly limit?: number;
@@ -142,9 +130,6 @@ export class AISubscriptionError extends AIError {
   }
 }
 
-/**
- * Error for model access restriction (403 upgrade_required).
- */
 export class AIModelRestrictionError extends AIError {
   constructor(
     message: string = 'This model requires a Pro subscription.',
@@ -155,9 +140,6 @@ export class AIModelRestrictionError extends AIError {
   }
 }
 
-/**
- * Error for AI provider failures (OpenAI, Google, Anthropic API errors).
- */
 export class AIProviderError extends AIError {
   readonly provider?: string;
 
@@ -171,9 +153,6 @@ export class AIProviderError extends AIError {
   }
 }
 
-/**
- * Error for invalid/malformed AI responses.
- */
 export class AIResponseError extends AIError {
   constructor(message: string = 'Invalid response from AI service.', options?: { requestId?: string; details?: Record<string, unknown> }) {
     super(message, options);
@@ -181,9 +160,6 @@ export class AIResponseError extends AIError {
   }
 }
 
-/**
- * Custom error for request timeouts.
- */
 export class TimeoutError extends AIError {
   constructor(message: string = 'Request timed out. Please try again.') {
     super(message, { statusCode: 408 });
@@ -191,9 +167,6 @@ export class TimeoutError extends AIError {
   }
 }
 
-/**
- * Type guards for error checking.
- */
 export function isAIAuthError(error: unknown): error is AIAuthError {
   return error instanceof AIAuthError || (error instanceof Error && error.name === 'AIAuthError');
 }
@@ -237,7 +210,6 @@ async function callSupabaseAI(
   const { data: sessionData } = await supabase.auth.getSession();
   const accessToken = sessionData.session?.access_token;
 
-  // Log request details in development
   if (DEBUG) {
     console.log(`[AI Request ${requestId}]`, {
       feature,
@@ -248,7 +220,6 @@ async function callSupabaseAI(
     });
   }
 
-  // Require authentication for AI features
   if (!accessToken) {
     throw new AIAuthError('Please sign in to use AI features', { requestId });
   }
@@ -275,7 +246,6 @@ async function callSupabaseAI(
 
     const elapsed = Math.round(performance.now() - startTime);
 
-    // Log response in development
     if (DEBUG) {
       console.log(`[AI Response ${requestId}] ${elapsed}ms`, {
         hasData: !!data,
@@ -285,19 +255,16 @@ async function callSupabaseAI(
       });
     }
 
-    // Handle Supabase function invoke errors
     if (error) {
       const errorPayload = await extractSupabaseErrorPayload(error);
       const errorDetails = mapAIError(error, requestId, provider, config.model, errorPayload);
       throw errorDetails;
     }
 
-    // Handle response with error field (from edge function)
     if (data?.error) {
       const errorMessage = data.error as string;
       const errorCode = data.code as string | undefined;
 
-      // Subscription errors (402 / trial expired / limit reached)
       if (errorCode === 'trial_expired' || errorCode === 'limit_reached') {
         throw new AISubscriptionError(errorMessage, {
           statusCode: 402,
@@ -308,12 +275,10 @@ async function callSupabaseAI(
         });
       }
 
-      // Model restriction (403 / upgrade_required)
       if (errorCode === 'upgrade_required') {
         throw new AIModelRestrictionError(errorMessage, { requestId });
       }
 
-      // Rate limit error from edge function
       const normalizedErrorMessage = errorMessage.toLowerCase();
       if (data.limit !== undefined || normalizedErrorMessage.includes('rate limit') || normalizedErrorMessage.includes('limit exceeded')) {
         throw new AIRateLimitError(errorMessage, {
@@ -323,7 +288,6 @@ async function callSupabaseAI(
         });
       }
 
-      // Provider error (OpenAI, Google, etc.)
       if (isProviderErrorMessage(errorMessage) || isProviderErrorCode(errorCode)) {
         throw new AIProviderError(errorMessage, {
           requestId,
@@ -332,11 +296,9 @@ async function callSupabaseAI(
         });
       }
 
-      // Generic error from edge function
       throw new AIError(errorMessage, { statusCode: 500, requestId });
     }
 
-    // Validate response has expected output
     if (!data?.output) {
       throw new AIResponseError('AI response missing output field', { requestId, details: { data } });
     }
@@ -350,38 +312,18 @@ async function callSupabaseAI(
 
     return data;
   } catch (err) {
-    // Re-throw our custom errors
-    if (err instanceof AIError) {
-      throw err;
-    }
-
-    // Handle timeout
-    if (err instanceof TimeoutError) {
-      throw err;
-    }
+    if (err instanceof AIError) throw err;
+    if (err instanceof TimeoutError) throw err;
+    if (err instanceof DOMException && err.name === 'AbortError') throw new TimeoutError();
 
-    // Handle abort (our timeout triggered)
-    if (err instanceof DOMException && err.name === 'AbortError') {
-      throw new TimeoutError();
-    }
-
-    // Wrap unknown errors
     const message = err instanceof Error ? err.message : 'Unknown error occurred';
-
-    // Check if the error message indicates an abort/timeout
-    if (message.includes('abort') || message.includes('signal')) {
-      throw new TimeoutError();
-    }
-
+    if (message.includes('abort') || message.includes('signal')) throw new TimeoutError();
     throw new AIError(message, { requestId });
   } finally {
     clearTimeout(timeoutId);
   }
 }
 
-/**
- * Parse Supabase FunctionsHttpError into appropriate AIError subclass.
- */
 function getSupabaseErrorStatus(error: { context?: unknown }): number | undefined {
   const context = error.context;
   if (context && typeof context === 'object' && 'status' in context) {
@@ -425,32 +367,20 @@ export function mapAIError(
   const message = payloadMessage || error.message || 'Unknown error';
   const errorCode = typeof payload?.code === 'string' ? payload.code : undefined;
 
-  // Detect abort/signal errors and treat as timeout
   if (message.includes('abort') || message.includes('signal')) {
     return new TimeoutError();
   }
 
-  // Try to extract status code from error context or message
   let statusCode: number | undefined = getSupabaseErrorStatus(error);
 
-  // Parse status from message patterns if status is missing
   if (message.includes('non-2xx') || message.includes('status code')) {
-    // Common message: "Edge Function returned a non-2xx status code"
-    // Check for hints in message
-    if (message.includes('401') || message.includes('Unauthorized')) {
-      statusCode = 401;
-    } else if (message.includes('402')) {
-      statusCode = 402;
-    } else if (message.includes('403') || message.includes('Forbidden')) {
-      statusCode = 403;
-    } else if (message.includes('429') || message.includes('rate limit')) {
-      statusCode = 429;
-    } else if (message.includes('500') || message.includes('Internal')) {
-      statusCode = 500;
-    }
+    if (message.includes('401') || message.includes('Unauthorized')) statusCode = 401;
+    else if (message.includes('402')) statusCode = 402;
+    else if (message.includes('403') || message.includes('Forbidden')) statusCode = 403;
+    else if (message.includes('429') || message.includes('rate limit')) statusCode = 429;
+    else if (message.includes('500') || message.includes('Internal')) statusCode = 500;
   }
 
-  // Return appropriate error type based on status code
   if (statusCode === 401) {
     return new AIAuthError(
       'Authentication failed. Your session may have expired. Please sign in again.',
@@ -471,7 +401,6 @@ export function mapAIError(
 
   if (statusCode === 403) {
     const code = typeof payload?.code === 'string' ? payload.code : undefined;
-    // Could be auth failure or model restriction
     if (code === 'upgrade_required' || message.includes('model') || message.includes('upgrade')) {
       return new AIModelRestrictionError(message, { requestId });
     }
@@ -499,7 +428,6 @@ export function mapAIError(
     });
   }
 
-  // Default: return generic error with helpful message
   return new AIError(
     `AI service error: ${message}. Please try again.`,
     { statusCode: statusCode || 500, requestId }
@@ -533,14 +461,8 @@ function cleanGeneratedOutput<T>(value: T): T {
   return value;
 }
 
-/**
- * Transforms AI generate response from various formats to the expected GenerateOutput schema.
- * This handles cases where the AI returns a different structure than requested.
- */
 function transformGenerateResponse(response: Record<string, unknown>): GenerateOutput {
-  // If already in correct format, return as-is (with exordio preserved)
   if (response.caseStructure && response.contentions && response.predictedOpponentCase && response.counters && response.metadata) {
-    // Ensure exordio is properly structured if present
     const result = response as unknown as GenerateOutput;
     if (response.exordio && typeof response.exordio === 'object') {
       const ex = response.exordio as Record<string, unknown>;
@@ -552,7 +474,6 @@ function transformGenerateResponse(response: Record<string, unknown>): GenerateO
     return cleanGeneratedOutput(result);
   }
 
-  // Transform from wrong format to correct format
   const wrongFormatContentions = response.contentions as Array<{
     title?: string;
     claim?: string;
@@ -573,7 +494,6 @@ function transformGenerateResponse(response: Record<string, unknown>): GenerateO
     impact: c.impact || c.analysis || '',
   }));
 
-  // Transform rebuttals to counters
   const rebuttals = (response.rebuttals as Array<{ attack?: string; response?: string }>) || [];
   const counters = rebuttals.map(r => ({
     targetArgument: r.attack || '',
@@ -581,7 +501,6 @@ function transformGenerateResponse(response: Record<string, unknown>): GenerateO
     rebuttal: r.response || '',
   }));
 
-  // Transform potentialWeaknesses to predictedOpponentCase
   const weaknesses = (response.potentialWeaknesses as string[]) || [];
 
   const result: GenerateOutput = {
@@ -617,7 +536,6 @@ function transformGenerateResponse(response: Record<string, unknown>): GenerateO
     },
   };
 
-  // Preserve exordio if present in the original response
   if (response.exordio && typeof response.exordio === 'object') {
     const ex = response.exordio as Record<string, unknown>;
     result.exordio = {
@@ -629,12 +547,7 @@ function transformGenerateResponse(response: Record<string, unknown>): GenerateO
   return cleanGeneratedOutput(result);
 }
 
-/**
- * Transforms AI brainstorm response to ensure all required fields exist.
- * This handles cases where the AI returns incomplete structures.
- */
 function transformBrainstormResponse(response: Record<string, unknown>): BrainstormOutput {
-  // Ensure required base fields exist
   const result: BrainstormOutput = {
     needsMoreInfo: Boolean(response.needsMoreInfo),
     clarifyingQuestions: Array.isArray(response.clarifyingQuestions) ? response.clarifyingQuestions : [],
@@ -642,7 +555,6 @@ function transformBrainstormResponse(response: Record<string, unknown>): Brainst
     warningsAndTradeoffs: Array.isArray(response.warningsAndTradeoffs) ? response.warningsAndTradeoffs : [],
   };
 
-  // Helper to normalize an Idea object
   const normalizeIdea = (idea: unknown): { id: string; title: string; description: string; side: 'pro' | 'con' | 'neutral'; strength: 'strong' | 'moderate' | 'weak'; tradeoffs: string[]; relatedTo: string[] } | null => {
     if (!idea || typeof idea !== 'object') return null;
     const i = idea as Record<string, unknown>;
@@ -675,12 +587,10 @@ function transformBrainstormResponse(response: Record<string, unknown>): Brainst
     })
     .filter((item): item is NonNullable<typeof item> => item !== null);
 
-  // Transform topFive if present
   if (response.topFive && Array.isArray(response.topFive)) {
     result.topFive = normalizeTopFiveItems(response.topFive);
   }
 
-  // Transform mindmap if present
   if (response.mindmap && Array.isArray(response.mindmap)) {
     result.mindmap = response.mindmap
       .map((category: unknown) => {
@@ -697,7 +607,6 @@ function transformBrainstormResponse(response: Record<string, unknown>): Brainst
       .filter((cat): cat is NonNullable<typeof cat> => cat !== null && cat.items.length > 0);
   }
 
-  // Transform buckets if present
   if (response.buckets && Array.isArray(response.buckets)) {
     result.buckets = response.buckets
       .map((bucket: unknown) => {
@@ -726,11 +635,6 @@ function transformBrainstormResponse(response: Record<string, unknown>): Brainst
   return cleanGeneratedOutput(result);
 }
 
-/**
- * Validates the attack response at the trust boundary. Attack outputs were
- * previously cast without validation; now malformed provider responses fail
- * loudly instead of rendering unverified shapes.
- */
 function validateAttackOutput(output: unknown): AttackOutput {
   const parsed = AttackOutputSchema.safeParse(output);
   if (!parsed.success) {
@@ -741,7 +645,6 @@ function validateAttackOutput(output: unknown): AttackOutput {
   return parsed.data;
 }
 
-/** Validates the transformed generate response before it can be rendered or persisted alongside sources. */
 function validateGenerateOutput(output: unknown): GenerateOutput {
   const parsed = GenerateOutputSchema.safeParse(output);
   if (!parsed.success) {
@@ -789,13 +692,10 @@ async function autosaveDiscoveredSources(sources: DiscoveredSource[], capturedVi
 
 function expectedContentionCount(length: GenerateInput['length']): number {
   switch (length) {
-    case 'standard':
-      return 3;
-    case 'comprehensive':
-      return 4;
+    case 'standard': return 3;
+    case 'comprehensive': return 4;
     case 'brief':
-    default:
-      return 2;
+    default: return 2;
   }
 }
 
@@ -803,7 +703,6 @@ export async function generateCase(input: GenerateInput, config: ProviderConfig)
   if (config.provider === 'mock') {
     return { result: await mockGenerateCase(input.motion, input.side, input.length), discoveredSources: [] };
   }
-  // Inject global language into input for the edge function
   const language = useSettingsStore.getState().outputLanguage;
   const inputWithLanguage = { ...input, language } as Record<string, unknown>;
   const data = await callSupabaseAI('generate', inputWithLanguage, config) as { output: unknown; discoveredSources?: unknown };
@@ -818,10 +717,7 @@ export async function generateCase(input: GenerateInput, config: ProviderConfig)
   const discovered = parseDiscoveredSources(data.discoveredSources);
   await autosaveDiscoveredSources(discovered, 'generate');
 
-  return {
-    result,
-    discoveredSources: discovered,
-  };
+  return { result, discoveredSources: discovered };
 }
 
 export async function attackCase(input: AttackInput, config: ProviderConfig): Promise<ResultWithSources<AttackOutput>> {
@@ -830,11 +726,7 @@ export async function attackCase(input: AttackInput, config: ProviderConfig): Pr
   const result = validateAttackOutput(data.output);
   const discovered = parseDiscoveredSources(data.discoveredSources);
   await autosaveDiscoveredSources(discovered, 'attack');
-
-  return {
-    result,
-    discoveredSources: discovered,
-  };
+  return { result, discoveredSources: discovered };
 }
 
 export async function brainstorm(input: BrainstormInput, config: ProviderConfig): Promise<ResultWithSources<BrainstormOutput>> {
@@ -842,16 +734,17 @@ export async function brainstorm(input: BrainstormInput, config: ProviderConfig)
   const data = await callSupabaseAI('brainstorm', input as Record<string, unknown>, config) as { output: unknown; discoveredSources?: unknown };
   const discovered = parseDiscoveredSources(data.discoveredSources);
   await autosaveDiscoveredSources(discovered, 'brainstorm');
-
   return {
     result: transformBrainstormResponse(data.output as Record<string, unknown>),
     discoveredSources: discovered,
   };
 }
 
-export async function factoids(input: FactoidsInput, config: ProviderConfig): Promise<FactoidsOutput> {
-  if (config.provider === 'mock') return mockFactoids(input.claim);
-  // Inject global language into input for the edge function
+export async function factoids(input: FactoidsInput, config: ProviderConfig): Promise<ResultWithSources<FactoidsOutput>> {
+  if (config.provider === 'mock') {
+    return { result: await mockFactoids(input.claim), discoveredSources: [] };
+  }
+
   const language = useSettingsStore.getState().outputLanguage;
   const inputWithLanguage = {
     ...input,
@@ -859,7 +752,7 @@ export async function factoids(input: FactoidsInput, config: ProviderConfig): Pr
     sourceCount: input.sourceCount || 5,
     language,
   } as Record<string, unknown>;
-  const data = await callSupabaseAI('factoids', inputWithLanguage, config) as { output: unknown };
+  const data = await callSupabaseAI('factoids', inputWithLanguage, config) as { output: unknown; discoveredSources?: unknown };
   const parsed = FactoidsOutputSchema.safeParse(data.output);
   if (!parsed.success) {
     throw new AIResponseError('AI response did not match the expected factoids schema.', {
@@ -870,11 +763,16 @@ export async function factoids(input: FactoidsInput, config: ProviderConfig): Pr
   const allFactoids = parsed.data.factoids;
   const verifiedFactoids = allFactoids.filter((factoid) => factoid.citation.verified === 'verified');
   const returnedFactoids = verifiedFactoids.slice(0, input.sourceCount || 5);
-  return {
+  const result: FactoidsOutput = {
     ...parsed.data,
     factoids: returnedFactoids,
     filteredOutCount: Math.max(0, allFactoids.length - returnedFactoids.length),
   };
+
+  return {
+    result,
+    discoveredSources: parseDiscoveredSources(data.discoveredSources),
+  };
 }
 
 export interface AskChatOptions {
@@ -909,4 +807,4 @@ export async function askChat(
     });
   }
   return parsed.data;
-}
+}
\ No newline at end of file

From f8da4ad8c425af7beebd2ad8ca32f02ea1ed584c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:44:14 +0200
Subject: [PATCH 66/84] feat: show Factoids consulted-source provenance

---
 src/pages/FactoidsPage.tsx | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/src/pages/FactoidsPage.tsx b/src/pages/FactoidsPage.tsx
index dd5408816..59356ae33 100644
--- a/src/pages/FactoidsPage.tsx
+++ b/src/pages/FactoidsPage.tsx
@@ -1,10 +1,11 @@
+import { useState } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { useTranslation } from 'react-i18next';
 import { useSessionStore } from '@/lib/stores/session-store';
 import { useSettingsStore } from '@/lib/stores/settings-store';
 import { FactoidsForm } from '@/components/features/factoids/FactoidsForm';
 import { FactoidsResults } from '@/components/features/factoids/FactoidsResults';
-import { factoids, askChat } from '@/lib/ai/client';
+import { factoids, askChat, type DiscoveredSource } from '@/lib/ai/client';
 import { useSubscriptionError } from '@/hooks/use-subscription-error';
 import { getUserFacingAIError } from '@/lib/ai/error-display';
 import { LimitReachedModal, ModelRestrictedModal, PricingModal } from '@/components/features/subscription';
@@ -22,11 +23,14 @@ export default function FactoidsPage() {
   const navigate = useNavigate();
   const subError = useSubscriptionError();
   const { t } = useTranslation();
+  const [consultedSources, setConsultedSources] = useState<DiscoveredSource[]>([]);
 
   const handleSubmit = async (data: FactoidsInput) => {
     setFactoidsLoading(true);
+    setConsultedSources([]);
     try {
-      const result = await factoids(data, config);
+      const { result, discoveredSources } = await factoids(data, config);
+      setConsultedSources(discoveredSources);
       setFactoidsResult(result);
       toast({ title: t('factoids.complete', 'Research complete'), description: t('factoids.completeDesc', 'Verified evidence is ready.'), variant: 'success' });
     } catch (error) {
@@ -115,12 +119,10 @@ export default function FactoidsPage() {
         </AnimatedSection>
 
         <div className="grid gap-8 lg:grid-cols-[400px_1fr]">
-          {/* Form */}
           <AnimatedSection delay={75} className="lg:sticky lg:top-24 lg:self-start">
             <FactoidsForm onSubmit={handleSubmit} isLoading={factoidsLoading} />
           </AnimatedSection>
 
-          {/* Results */}
           <AnimatedSection delay={150}>
             {factoidsLoading ? (
               <div key="factoids-loading" className="motion-swap motion-shimmer flex min-h-[400px] flex-col items-center justify-center rounded-lg border-2 border-dashed border-secondary/30 bg-secondary/5 p-8">
@@ -130,6 +132,7 @@ export default function FactoidsPage() {
               <div key="factoids-results" className="motion-swap">
                 <FactoidsResults
                   result={factoidsResult}
+                  consultedSources={consultedSources}
                   onDiscuss={handleDiscuss}
                   onSaveSource={handleSaveToLibrary}
                   onUseSuggestion={handleUseSuggestion}

From 54313091088be3dd524b056ae31a4c687be094c7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:44:50 +0200
Subject: [PATCH 67/84] feat: render all Factoids consulted sources

---
 .../features/factoids/FactoidsResults.tsx     | 42 +++++++++----------
 1 file changed, 20 insertions(+), 22 deletions(-)

diff --git a/src/components/features/factoids/FactoidsResults.tsx b/src/components/features/factoids/FactoidsResults.tsx
index ff622a5a9..096bb8060 100644
--- a/src/components/features/factoids/FactoidsResults.tsx
+++ b/src/components/features/factoids/FactoidsResults.tsx
@@ -7,6 +7,7 @@ import { Button } from '@/components/ui/button';
 import { SectionCard } from '@/components/ui/section-card';
 import { Progress } from '@/components/ui/progress';
 import type { FactoidsOutput, Factoid } from '@/lib/ai/schemas/factoids';
+import type { DiscoveredSource } from '@/lib/ai/client';
 import { StaggeredContainer } from '@/components/ui/animated-section';
 import { cn } from '@/lib/utils';
 import { validateUrl } from '@/lib/validation/url';
@@ -15,11 +16,12 @@ import { exportFactoidsToDocx, exportFactoidsToGoogleDocs } from '@/lib/export-u
 import { toast } from 'sonner';
 import { ExportToolbar } from '@/components/features/ExportToolbar';
 import { GoogleDriveAuthModal } from '@/components/features/export/GoogleDriveAuthModal';
+import { SourceQualityList } from '@/components/features/shared/SourceQualityList';
 import { openExternalUrl } from '@/lib/native';
 
-
 interface FactoidsResultsProps {
   result: FactoidsOutput;
+  consultedSources?: DiscoveredSource[];
   onDiscuss?: () => void;
   onSaveSource?: (title: string, content: string, url?: string) => void;
   onUseSuggestion?: (query: string) => void;
@@ -33,16 +35,13 @@ const verificationConfig = {
 
 function FactoidCard({ factoid, onSave }: { factoid: Factoid, onSave?: FactoidsResultsProps['onSaveSource'] }) {
   const { t } = useTranslation();
-  // Defensive check for old data format in localStorage
   const verified = factoid.citation?.verified ?? 'pending';
   const config = verificationConfig[verified] ?? verificationConfig.pending;
   const VerifyIcon = config.icon;
-  // Use secure URL validation instead of simple string checks
   const safeUrl = validateUrl(factoid.citation?.url);
 
   return (
     <div className="rounded-lg border border-border bg-card p-4 space-y-4 motion-list-item card-hover-glow">
-      {/* Header */}
       <div className="flex items-start justify-between gap-2">
         <div className="flex-1">
           {safeUrl ? (
@@ -86,13 +85,11 @@ function FactoidCard({ factoid, onSave }: { factoid: Factoid, onSave?: FactoidsR
         </div>
       </div>
 
-      {/* Key Figure */}
       <div className="rounded-md bg-primary/5 border border-primary/20 p-3 text-left">
         <span className="text-sm font-medium text-primary">{t('factoidsResults.keyFigure')} </span>
         <span className="text-lg font-bold text-foreground">{factoid.keyFigure}</span>
       </div>
 
-      {/* Context & Limitations */}
       <div className="space-y-2 text-sm text-left">
         <div>
           <span className="font-medium text-muted-foreground">{t('factoidsResults.context')} </span>
@@ -104,7 +101,6 @@ function FactoidCard({ factoid, onSave }: { factoid: Factoid, onSave?: FactoidsR
         </div>
       </div>
 
-      {/* Citation Block */}
       <div className="rounded-md bg-muted/50 p-3 space-y-1 text-sm text-left">
         <div className="font-medium text-foreground">{factoid.citation?.title || t('factoidsResults.unknownSource')}</div>
         <div className="text-muted-foreground">
@@ -125,7 +121,6 @@ function FactoidCard({ factoid, onSave }: { factoid: Factoid, onSave?: FactoidsR
         )}
       </div>
 
-      {/* How to Use */}
       <div className="flex items-start gap-2 text-sm">
         <Lightbulb className="h-4 w-4 text-amber-500 mt-0.5 shrink-0" />
         <div>
@@ -137,7 +132,7 @@ function FactoidCard({ factoid, onSave }: { factoid: Factoid, onSave?: FactoidsR
   );
 }
 
-export function FactoidsResults({ result, onDiscuss, onSaveSource, onUseSuggestion }: FactoidsResultsProps) {
+export function FactoidsResults({ result, consultedSources = [], onDiscuss, onSaveSource, onUseSuggestion }: FactoidsResultsProps) {
   const { t } = useTranslation();
   const [isExportingGDocs, setIsExportingGDocs] = useState(false);
   const [showDriveAuth, setShowDriveAuth] = useState(false);
@@ -150,11 +145,8 @@ export function FactoidsResults({ result, onDiscuss, onSaveSource, onUseSuggesti
 
   const handleDocxExport = async () => {
     const success = await exportFactoidsToDocx(result);
-    if (success) {
-      toast.success(t('factoidsResults.exportedDocx'));
-    } else {
-      toast.error(t('factoidsResults.exportFailedDocx'));
-    }
+    if (success) toast.success(t('factoidsResults.exportedDocx'));
+    else toast.error(t('factoidsResults.exportFailedDocx'));
   };
 
   const handleGoogleDocsExport = async () => {
@@ -165,10 +157,7 @@ export function FactoidsResults({ result, onDiscuss, onSaveSource, onUseSuggesti
         const openDocument = (): void => void openExternalUrl(exportResult.documentUrl!, { newWindow: true })
           .catch(() => toast.error(t('factoidsResults.exportError')));
         toast.success(t('factoidsResults.exportedGdocs'), {
-          action: {
-            label: t('factoidsResults.open'),
-            onClick: openDocument,
-          },
+          action: { label: t('factoidsResults.open'), onClick: openDocument },
         });
         openDocument();
       } else if (exportResult.requiresReauth) {
@@ -195,7 +184,6 @@ export function FactoidsResults({ result, onDiscuss, onSaveSource, onUseSuggesti
         discussLabel={t('factoidsResults.discuss')}
       />
 
-      {/* Verification Status */}
       <SectionCard
         title={t('factoidsResults.verificationStatus')}
         description={`${verifiedCount} ${t('factoidsResults.verified')}`}
@@ -212,7 +200,6 @@ export function FactoidsResults({ result, onDiscuss, onSaveSource, onUseSuggesti
         </div>
       </SectionCard>
 
-      {/* Warnings */}
       {warnings.length > 0 && (
         <div className="rounded-lg border border-amber-500/30 bg-amber-500/5 p-4">
           <div className="flex items-center gap-2 mb-2">
@@ -230,7 +217,19 @@ export function FactoidsResults({ result, onDiscuss, onSaveSource, onUseSuggesti
         </div>
       )}
 
-      {/* Factoids */}
+      {consultedSources.length > 0 && (
+        <SectionCard
+          title={t('factoidsResults.consultedSources', 'Sources consulted')}
+          description={t(
+            'factoidsResults.consultedSourcesDesc',
+            'These pages informed the research pass. Quality chips show why a source was trusted or kept as fallback context; only verified evidence appears as a factoid above.',
+          )}
+          icon={<Search className="h-5 w-5" />}
+        >
+          <SourceQualityList sources={consultedSources} />
+        </SectionCard>
+      )}
+
       <SectionCard
         title={`${t('factoidsResults.found')} ${displayFactoids.length} ${t('factoidsResults.factoids')}`}
         description={t('factoidsResults.factoidsDesc')}
@@ -247,7 +246,6 @@ export function FactoidsResults({ result, onDiscuss, onSaveSource, onUseSuggesti
         </div>
       </SectionCard>
 
-      {/* Search Suggestions */}
       <SectionCard
         title={t('factoidsResults.findMore')}
         description={t('factoidsResults.findMoreDesc')}

From 3c34dd36e786bf2174d75f1cc104b6d3f37101d0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:46:10 +0200
Subject: [PATCH 68/84] test: keep Factoids page compatible with legacy mocks

---
 src/pages/FactoidsPage.tsx | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/src/pages/FactoidsPage.tsx b/src/pages/FactoidsPage.tsx
index 59356ae33..a7af6a388 100644
--- a/src/pages/FactoidsPage.tsx
+++ b/src/pages/FactoidsPage.tsx
@@ -9,7 +9,7 @@ import { factoids, askChat, type DiscoveredSource } from '@/lib/ai/client';
 import { useSubscriptionError } from '@/hooks/use-subscription-error';
 import { getUserFacingAIError } from '@/lib/ai/error-display';
 import { LimitReachedModal, ModelRestrictedModal, PricingModal } from '@/components/features/subscription';
-import type { FactoidsInput } from '@/lib/ai/schemas/factoids';
+import type { FactoidsInput, FactoidsOutput } from '@/lib/ai/schemas/factoids';
 import { useToast } from '@/hooks/use-toast';
 import { StreamingIndicator } from '@/components/ui/streaming-indicator';
 import { AnimatedSection } from '@/components/ui/animated-section';
@@ -29,7 +29,14 @@ export default function FactoidsPage() {
     setFactoidsLoading(true);
     setConsultedSources([]);
     try {
-      const { result, discoveredSources } = await factoids(data, config);
+      const outcome = await factoids(data, config);
+      // Runtime compatibility for older saved/test callers that mocked the old
+      // direct FactoidsOutput return shape before provenance was exposed.
+      const hasEnvelope = outcome && typeof outcome === 'object' && 'result' in outcome;
+      const result = (hasEnvelope ? outcome.result : outcome) as FactoidsOutput;
+      const discoveredSources = hasEnvelope && Array.isArray(outcome.discoveredSources)
+        ? outcome.discoveredSources
+        : [];
       setConsultedSources(discoveredSources);
       setFactoidsResult(result);
       toast({ title: t('factoids.complete', 'Research complete'), description: t('factoids.completeDesc', 'Verified evidence is ready.'), variant: 'success' });

From 1ffe13adca813c41a3ee31416c0d97e78228c843 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:46:26 +0200
Subject: [PATCH 69/84] test: cover Factoids consulted-source quality panel

---
 src/test/components/FactoidsResults.test.tsx | 33 ++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/src/test/components/FactoidsResults.test.tsx b/src/test/components/FactoidsResults.test.tsx
index da05479a5..9c4d921e7 100644
--- a/src/test/components/FactoidsResults.test.tsx
+++ b/src/test/components/FactoidsResults.test.tsx
@@ -35,3 +35,36 @@ test('does not expose source verification while no verification behavior exists'
 
   expect(screen.queryByRole('button', { name: /verify all sources/i })).not.toBeInTheDocument();
 });
+
+test('shows every consulted source with quality labels and weak-source warning', () => {
+  render(
+    <FactoidsResults
+      result={result}
+      consultedSources={[
+        {
+          title: 'Official statistics',
+          url: 'https://www.census.gov/example',
+          sourceType: 'government',
+          qualityLabel: 'strong',
+          qualityScore: 92,
+          query: 'official statistics',
+        },
+        {
+          title: 'Broad fallback discussion',
+          url: 'https://www.reddit.com/r/example',
+          sourceType: 'social',
+          qualityLabel: 'weak',
+          qualityScore: 18,
+          query: 'broad discussion',
+        },
+      ]}
+    />,
+  );
+
+  expect(screen.getByText('Sources consulted')).toBeInTheDocument();
+  expect(screen.getByText('Official statistics')).toBeInTheDocument();
+  expect(screen.getByText('Broad fallback discussion')).toBeInTheDocument();
+  expect(screen.getByText('strong')).toBeInTheDocument();
+  expect(screen.getByText('weak')).toBeInTheDocument();
+  expect(screen.getByText(/fallback context only/i)).toBeInTheDocument();
+});

From 7bf6203af3aff52f3ebfead6860f5be6cd482c8e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:46:48 +0200
Subject: [PATCH 70/84] test: preserve Factoids discovered-source provenance

---
 src/test/ai/factoids-provenance.test.ts | 106 ++++++++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 src/test/ai/factoids-provenance.test.ts

diff --git a/src/test/ai/factoids-provenance.test.ts b/src/test/ai/factoids-provenance.test.ts
new file mode 100644
index 000000000..7c69b9910
--- /dev/null
+++ b/src/test/ai/factoids-provenance.test.ts
@@ -0,0 +1,106 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { resetMockState, setMockInvokeResponse, setMockSessionToken, supabaseMock } from '@/test/mocks/supabase';
+
+vi.mock('@/lib/supabase/client', () => ({ supabase: supabaseMock }));
+vi.mock('@/lib/stores/settings-store', () => ({
+  useSettingsStore: {
+    getState: () => ({ customSystemPrompt: undefined, outputLanguage: 'en' }),
+  },
+}));
+vi.mock('@/lib/stores/session-store', () => ({
+  useSessionStore: {
+    getState: () => ({ sourceLibrary: [] }),
+  },
+}));
+
+import { factoids } from '@/lib/ai/client';
+
+const config = { provider: 'google', model: 'gemini-3-flash-preview', temperature: 0.3 };
+
+describe('Factoids provenance boundary', () => {
+  beforeEach(() => {
+    resetMockState();
+    setMockSessionToken('valid-token');
+    vi.clearAllMocks();
+  });
+
+  it('returns validated consulted sources separately from verified evidence', async () => {
+    setMockInvokeResponse({
+      output: {
+        factoids: [{
+          id: 'fact-1',
+          shortClaim: 'Transit ridership increased.',
+          keyFigure: '12%',
+          context: 'A measured increase after a fare policy change.',
+          limitations: 'Single-city result.',
+          citation: {
+            title: 'Transport report',
+            publisher: 'City agency',
+            url: 'https://transport.example.gov/report',
+            verified: 'verified',
+          },
+          howToUse: 'Use as a narrow empirical example.',
+          relevanceScore: 88,
+        }],
+        searchSuggestions: [],
+        warnings: [],
+        verificationStatus: 'complete',
+      },
+      discoveredSources: [
+        {
+          title: 'Transport report',
+          url: 'https://transport.example.gov/report',
+          content: 'Agency report text',
+          sourceType: 'government',
+          qualityScore: 91,
+          qualityLabel: 'strong',
+          query: 'fare policy ridership report',
+        },
+        {
+          title: 'Forum discussion',
+          url: 'https://www.reddit.com/r/transit/example',
+          content: 'Anecdotal discussion',
+          sourceType: 'social',
+          qualityScore: 18,
+          qualityLabel: 'weak',
+          query: 'fare policy ridership discussion',
+        },
+        { title: '', url: 'https://invalid.example' },
+      ],
+    });
+
+    const outcome = await factoids({
+      claim: 'Free transit increases ridership',
+      direction: 'for',
+      region: 'Global',
+      sourceType: 'any',
+      timeframe: '2020-2026',
+      sourceCount: 5,
+    }, config);
+
+    expect(outcome.result.factoids).toHaveLength(1);
+    expect(outcome.discoveredSources).toHaveLength(2);
+    expect(outcome.discoveredSources[0]).toEqual(expect.objectContaining({
+      sourceType: 'government',
+      qualityLabel: 'strong',
+      qualityScore: 91,
+      query: 'fare policy ridership report',
+    }));
+    expect(outcome.discoveredSources[1].qualityLabel).toBe('weak');
+  });
+
+  it('keeps mock-provider Factoids inside the same result envelope', async () => {
+    const outcome = await factoids({
+      claim: 'Test claim',
+      direction: 'for',
+      region: 'Global',
+      sourceType: 'any',
+      timeframe: '',
+      sourceCount: 5,
+    }, { ...config, provider: 'mock' });
+
+    expect(outcome.result.factoids).toBeDefined();
+    expect(outcome.discoveredSources).toEqual([]);
+    expect(supabaseMock.functions.invoke).not.toHaveBeenCalled();
+  });
+});

From ce037eafcaefd453803458f8b28445408920020c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:47:54 +0200
Subject: [PATCH 71/84] test: support Deno serve handler overload in Vitest

---
 src/test/deno-compat.ts | 29 +++++++++++++----------------
 1 file changed, 13 insertions(+), 16 deletions(-)

diff --git a/src/test/deno-compat.ts b/src/test/deno-compat.ts
index 4fd7b2a85..c30b10a6f 100644
--- a/src/test/deno-compat.ts
+++ b/src/test/deno-compat.ts
@@ -38,7 +38,7 @@ if (!("Deno" in globalThis)) {
 
   // Loopback Deno.serve replacement: instead of binding a real socket, the
   // shim records the handler and routes matching fetch calls to it directly.
-  // Synchronous return with an addr object keeps Deno.serve call shapes valid.
+  // It supports both Deno.serve(handler) and Deno.serve(options, handler).
   type LoopbackHandler = (request: Request) => Response | Promise<Response>;
   let loopback: { matches: (url: URL) => boolean; handler: LoopbackHandler } | null = null;
   const LOOPBACK_DEFAULT_PORT = 43111;
@@ -50,12 +50,9 @@ if (!("Deno" in globalThis)) {
       const url = new URL(input instanceof Request ? input.url : String(input));
       if (loopback && loopback.matches(url)) {
         const response = await loopback.handler(new Request(url, init));
-        // Native fetch binds the caller's signal to the body stream so an
-        // aborted read rejects instead of stalling. Reproduce that here.
         const signal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
-        if (!signal || !response.body) {
-          return response;
-        }
+        if (!signal || !response.body) return response;
+
         const reader = response.body.getReader();
         const wired = new ReadableStream<Uint8Array>({
           start(controller) {
@@ -72,9 +69,7 @@ if (!("Deno" in globalThis)) {
             signal.addEventListener("abort", abort, { once: true });
             const pump = (): Promise<void> =>
               reader.read().then(({ done, value }) => {
-                if (signal.aborted) {
-                  return;
-                }
+                if (signal.aborted) return;
                 if (done) {
                   controller.close();
                   return;
@@ -93,15 +88,19 @@ if (!("Deno" in globalThis)) {
   }
 
   const serve = (
-    options: { hostname?: string; port?: number },
-    handler: LoopbackHandler,
+    optionsOrHandler: { hostname?: string; port?: number } | LoopbackHandler,
+    maybeHandler?: LoopbackHandler,
   ): {
     addr: { transport: string; hostname: string; port: number };
     shutdown: () => Promise<void>;
     finished: Promise<void>;
   } => {
-    const hostname = options?.hostname ?? "127.0.0.1";
-    const port = options?.port && options.port > 0 ? options.port : LOOPBACK_DEFAULT_PORT;
+    const options = typeof optionsOrHandler === "function" ? {} : optionsOrHandler;
+    const handler = typeof optionsOrHandler === "function" ? optionsOrHandler : maybeHandler;
+    if (!handler) throw new Error("Deno.serve shim requires a request handler");
+
+    const hostname = options.hostname ?? "127.0.0.1";
+    const port = options.port && options.port > 0 ? options.port : LOOPBACK_DEFAULT_PORT;
     loopback = {
       matches: (url) => url.hostname === hostname && url.port === String(port),
       handler,
@@ -128,9 +127,7 @@ if (!("Deno" in globalThis)) {
           : first && typeof first === "object" && "name" in first && typeof first.name === "string"
             ? first.name
             : "unnamed deno test";
-      it(name, () => {
-        return fn();
-      });
+      it(name, () => fn());
     },
     env: {
       get: (key: string): string | undefined => process.env[key],

From bfa93c3a903c9d889543df7af0652772eeb848cc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:48:05 +0200
Subject: [PATCH 72/84] test: add controllable Supabase Edge import adapter

---
 src/test/supabase-esm-shim.ts | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 src/test/supabase-esm-shim.ts

diff --git a/src/test/supabase-esm-shim.ts b/src/test/supabase-esm-shim.ts
new file mode 100644
index 000000000..43892167e
--- /dev/null
+++ b/src/test/supabase-esm-shim.ts
@@ -0,0 +1,21 @@
+import { createClient as realCreateClient } from '@supabase/supabase-js';
+import type { SupabaseClient, User } from '@supabase/supabase-js';
+
+export type { SupabaseClient, User };
+
+type CreateClient = typeof realCreateClient;
+
+declare global {
+  // Handler-boundary tests set this before dynamically importing an Edge
+  // Function entrypoint. Normal tests and production-like module imports fall
+  // back to the real installed Supabase client implementation.
+  // eslint-disable-next-line no-var
+  var __edgeSupabaseCreateClient: CreateClient | undefined;
+}
+
+export const createClient: CreateClient = ((...args: Parameters<CreateClient>) => {
+  if (globalThis.__edgeSupabaseCreateClient) {
+    return globalThis.__edgeSupabaseCreateClient(...args);
+  }
+  return realCreateClient(...args);
+}) as CreateClient;

From 5d8f0c17643460aea65354e2b4a4ed3ffd730041 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:48:24 +0200
Subject: [PATCH 73/84] test: resolve Edge Supabase imports in Vitest

---
 vitest.config.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/vitest.config.ts b/vitest.config.ts
index d47ad3a2c..e11440518 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -45,6 +45,10 @@ export default defineConfig({
         __dirname,
         "./src/test/deno-assert-shim.ts",
       ),
+      "https://esm.sh/@supabase/supabase-js@2": path.resolve(
+        __dirname,
+        "./src/test/supabase-esm-shim.ts",
+      ),
     },
   },
 });

From daf90d6080a13adf551931d2dde66608fc22b5d0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:49:12 +0200
Subject: [PATCH 74/84] test: exercise Factoids research through Edge handler
 boundary

---
 .../functions/ai/handler-research.test.ts     | 185 ++++++++++++++++++
 1 file changed, 185 insertions(+)
 create mode 100644 supabase/functions/ai/handler-research.test.ts

diff --git a/supabase/functions/ai/handler-research.test.ts b/supabase/functions/ai/handler-research.test.ts
new file mode 100644
index 000000000..fee8dca0d
--- /dev/null
+++ b/supabase/functions/ai/handler-research.test.ts
@@ -0,0 +1,185 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+function assert(condition: boolean, message: string) {
+  if (!condition) throw new Error(message);
+}
+
+Deno.test('Factoids handler carries filtered Exa research through to verified output and provenance', async () => {
+  const previousEnv = {
+    SUPABASE_URL: Deno.env.get('SUPABASE_URL'),
+    SUPABASE_SERVICE_ROLE_KEY: Deno.env.get('SUPABASE_SERVICE_ROLE_KEY'),
+    EXA_API_KEY: Deno.env.get('EXA_API_KEY'),
+    GOOGLE_API_KEY: Deno.env.get('GOOGLE_API_KEY'),
+  };
+  Deno.env.set('SUPABASE_URL', 'https://handler-test.supabase.co');
+  Deno.env.set('SUPABASE_SERVICE_ROLE_KEY', 'service-role-test');
+  Deno.env.set('EXA_API_KEY', 'exa-test');
+  Deno.env.set('GOOGLE_API_KEY', 'google-test');
+
+  const userId = '00000000-0000-0000-0000-000000000123';
+  const futureTrial = '2999-01-01T00:00:00.000Z';
+  const makeQuery = (table: string) => {
+    const query: any = {};
+    query.select = () => query;
+    query.eq = () => query;
+    query.in = () => query;
+    query.order = () => query;
+    query.limit = () => query;
+    query.is = () => query;
+    query.single = async () => {
+      if (table === 'user_roles') return { data: { role: 'user' }, error: null };
+      if (table === 'user_settings') {
+        return {
+          data: {
+            subscription_tier: 'trial',
+            daily_limit_override: 50,
+            trial_ends_at: futureTrial,
+            grace_period_ends_at: null,
+          },
+          error: null,
+        };
+      }
+      if (table === 'global_prompts') return { data: null, error: { message: 'not configured' } };
+      return { data: null, error: null };
+    };
+    query.maybeSingle = async () => ({ data: null, error: null });
+    query.insert = async () => ({ data: null, error: null });
+    return query;
+  };
+
+  const edgeSupabase = {
+    auth: {
+      getUser: async () => ({ data: { user: { id: userId } }, error: null }),
+    },
+    from: (table: string) => makeQuery(table),
+    rpc: async (name: string) => {
+      if (name !== 'consume_daily_quota') throw new Error(`Unexpected RPC: ${name}`);
+      return { data: [{ allowed: true, current_count: 1 }], error: null };
+    },
+  };
+
+  globalThis.__edgeSupabaseCreateClient = (() => edgeSupabase) as any;
+
+  const loopbackFetch = globalThis.fetch;
+  const exaSearchBodies: Array<Record<string, unknown>> = [];
+  let googleCalls = 0;
+  const sourceUrl = 'https://www.energy.gov/example-transit-policy-report';
+
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = new URL(input instanceof Request ? input.url : String(input));
+    if (url.hostname === '127.0.0.1' && url.port === '43111') {
+      return loopbackFetch(input, init);
+    }
+
+    if (url.hostname === 'api.exa.ai' && url.pathname === '/search') {
+      const body = JSON.parse(String(init?.body || '{}')) as Record<string, unknown>;
+      exaSearchBodies.push(body);
+      return new Response(JSON.stringify({
+        results: [{
+          title: 'Official transport affordability report',
+          url: sourceUrl,
+          text: 'Official government evidence about fare policy, access, ridership, and transport affordability with detailed methodology.',
+          publishedDate: '2026-03-01',
+        }],
+      }), { status: 200, headers: { 'content-type': 'application/json' } });
+    }
+
+    if (url.hostname === 'api.exa.ai' && url.pathname === '/contents') {
+      return new Response(JSON.stringify({
+        results: [{
+          title: 'Official transport affordability report',
+          url: sourceUrl,
+          text: 'The agency reports a 12 percent increase in ridership after the fare intervention. The report describes the study design and cautions that the result is specific to the measured program.',
+        }],
+      }), { status: 200, headers: { 'content-type': 'application/json' } });
+    }
+
+    if (url.hostname === 'generativelanguage.googleapis.com') {
+      googleCalls += 1;
+      const body = JSON.parse(String(init?.body || '{}')) as {
+        systemInstruction?: { parts?: Array<{ text?: string }> };
+      };
+      const systemText = body.systemInstruction?.parts?.[0]?.text || '';
+      const modelOutput = systemText.includes('research assistant')
+        ? { queries: [] }
+        : {
+            factoids: [{
+              id: 'fact-1',
+              shortClaim: 'The measured fare intervention increased ridership.',
+              keyFigure: '12%',
+              context: 'The government report measured a ridership increase after the fare intervention.',
+              limitations: 'The report concerns one measured program and should not be generalized without care.',
+              citation: {
+                title: 'Official transport affordability report',
+                publisher: 'Government agency',
+                date: '2026-03-01',
+                url: sourceUrl,
+                verified: 'pending',
+              },
+              howToUse: 'Use as a bounded empirical example, not a universal causal estimate.',
+              relevanceScore: 91,
+            }],
+            searchSuggestions: [],
+            warnings: ['Do not generalize beyond the measured program.'],
+            researchSummary: 'The official source supports a bounded empirical example.',
+            verificationStatus: 'pending',
+          };
+
+      return new Response(JSON.stringify({
+        candidates: [{ content: { parts: [{ text: JSON.stringify(modelOutput) }] } }],
+        usageMetadata: { promptTokenCount: 20, candidatesTokenCount: 10, totalTokenCount: 30 },
+      }), { status: 200, headers: { 'content-type': 'application/json' } });
+    }
+
+    throw new Error(`Unexpected external request in handler-boundary test: ${url.toString()}`);
+  }) as typeof fetch;
+
+  try {
+    await import('./index.ts?handler-research-test');
+
+    const response = await globalThis.fetch('http://127.0.0.1:43111', {
+      method: 'POST',
+      headers: {
+        authorization: 'Bearer test-user-token',
+        origin: 'http://localhost:8080',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        feature: 'factoids',
+        model: 'gemini-3-flash-preview',
+        temperature: 0.3,
+        input: {
+          claim: 'Fare-free public transport can increase ridership',
+          direction: 'for',
+          region: 'United States',
+          sourceType: 'government',
+          timeframe: '2020-2026',
+          sourceCount: 5,
+          language: 'en',
+        },
+        sources: [],
+      }),
+    });
+
+    assert(response.status === 200, `Expected handler 200, got ${response.status}: ${await response.text()}`);
+    const payload = await response.json() as {
+      output?: { factoids?: Array<{ citation?: { verified?: string; url?: string } }>; verificationStatus?: string };
+      discoveredSources?: Array<{ url?: string; qualityLabel?: string; sourceType?: string; query?: string }>;
+    };
+
+    assert(payload.output?.factoids?.length === 1, 'Expected one verified factoid');
+    assert(payload.output?.factoids?.[0]?.citation?.verified === 'verified', 'Fetched strong source should verify the citation');
+    assert(payload.output?.verificationStatus === 'complete', 'Handler should finalize verification status');
+    assert(payload.discoveredSources?.some((source) => source.url === sourceUrl && source.qualityLabel !== 'weak'), 'Expected consulted source provenance in handler response');
+    assert(exaSearchBodies.some((body) => Array.isArray(body.includeDomains)), 'Expected a government includeDomains request at the handler boundary');
+    assert(exaSearchBodies.every((body) => !String(body.query || '').includes('site:')), 'Handler must not emit site: query operators');
+    assert(googleCalls >= 2, `Expected follow-up-decision and main model calls, got ${googleCalls}`);
+  } finally {
+    globalThis.fetch = loopbackFetch;
+    globalThis.__edgeSupabaseCreateClient = undefined;
+    for (const [key, value] of Object.entries(previousEnv)) {
+      if (value === undefined) Deno.env.delete(key);
+      else Deno.env.set(key, value);
+    }
+  }
+});

From b631db33995e078c396237564c830ca5f1741e00 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:49:52 +0200
Subject: [PATCH 75/84] fix: use current Exa contents field names

---
 supabase/functions/import-source/index.ts | 21 +++++----------------
 1 file changed, 5 insertions(+), 16 deletions(-)

diff --git a/supabase/functions/import-source/index.ts b/supabase/functions/import-source/index.ts
index a1fcb33a3..93a75ca39 100644
--- a/supabase/functions/import-source/index.ts
+++ b/supabase/functions/import-source/index.ts
@@ -125,7 +125,7 @@ async function extractViaExa(requestedUrl: URL) {
       },
       body: JSON.stringify({
         urls: [requestedUrl.toString()],
-        text: { max_characters: MAX_CONTENT_CHARS },
+        text: { maxCharacters: MAX_CONTENT_CHARS },
       }),
       signal: controller.signal,
     });
@@ -157,8 +157,6 @@ async function extractViaExa(requestedUrl: URL) {
       try {
         finalUrl = validatePublicHttpUrl(returnedUrl);
       } catch {
-        // A provider-returned redirect URL is metadata only. If it does not
-        // satisfy our public URL policy, retain the already-validated request URL.
         finalUrl = requestedUrl;
       }
     }
@@ -178,24 +176,15 @@ async function extractViaExa(requestedUrl: URL) {
 Deno.serve(async (req) => {
   const corsHeaders = getCorsHeaders(req.headers.get("origin"));
 
-  if (req.method === "OPTIONS") {
-    return new Response("ok", { headers: corsHeaders });
-  }
-
-  if (req.method !== "POST") {
-    return jsonResponse({ error: "Method not allowed" }, 405, corsHeaders);
-  }
+  if (req.method === "OPTIONS") return new Response("ok", { headers: corsHeaders });
+  if (req.method !== "POST") return jsonResponse({ error: "Method not allowed" }, 405, corsHeaders);
 
   const authHeader = req.headers.get("authorization");
-  if (!authHeader?.startsWith("Bearer ")) {
-    return jsonResponse({ error: "Unauthorized" }, 401, corsHeaders);
-  }
+  if (!authHeader?.startsWith("Bearer ")) return jsonResponse({ error: "Unauthorized" }, 401, corsHeaders);
 
   const token = authHeader.slice(7);
   const { data: { user }, error: authError } = await supabase.auth.getUser(token);
-  if (authError || !user) {
-    return jsonResponse({ error: "Invalid token" }, 401, corsHeaders);
-  }
+  if (authError || !user) return jsonResponse({ error: "Invalid token" }, 401, corsHeaders);
 
   if (await isUserBanned(user.id)) {
     return jsonResponse({ error: "Your account has been suspended. Please contact support.", code: "banned" }, 403, corsHeaders);

From b7b1438403414f6a0d40b6da982961b259cd91ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:50:37 +0200
Subject: [PATCH 76/84] fix: classify filtered public-sector domains
 consistently

---
 supabase/functions/_shared/source-quality.ts | 8 +-------
 1 file changed, 1 insertion(+), 7 deletions(-)

diff --git a/supabase/functions/_shared/source-quality.ts b/supabase/functions/_shared/source-quality.ts
index 965ed6e93..fd7bb6dbe 100644
--- a/supabase/functions/_shared/source-quality.ts
+++ b/supabase/functions/_shared/source-quality.ts
@@ -130,6 +130,7 @@ function inferSourceType(result: ExaResult): SourceType {
   const host = hostFromUrl(url);
   const haystack = `${result.title || ""} ${url} ${result.content || result.description || ""}`;
 
+  if (GOVERNMENT_SEARCH_DOMAINS.some((domain) => hostMatchesDomain(host, domain))) return "government";
   if (/(^|\.)gov(\.|$)|\.gov\//i.test(host) || /\.europa\.eu$/i.test(host)) return "government";
   if (/\.edu$/i.test(host) || /\.ac\.[a-z]{2}$/i.test(host) || /\b(arxiv|jstor|ssrn|pubmed|springer|sciencedirect|nature|science\.org)\b/i.test(host)) return "academic";
   if (/\b(youtube\.com|youtu\.be)\b/i.test(host)) return "video";
@@ -260,12 +261,6 @@ function dedupeSearchRequests(requests: SearchRequest[]): SearchRequest[] {
   return accepted.slice(0, 6);
 }
 
-/**
- * Builds Exa search requests with filters represented as request fields rather
- * than query-operator text. This matches Exa's current API contract:
- * includeDomains for domain restrictions and category for news/research-paper
- * verticals. Callers may retry an unfiltered request if a filter returns zero.
- */
 export function buildSearchRequests(claim: string, region = "", preferredSourceType = "any", timeframe = ""): SearchRequest[] {
   const base = `${claim} ${region}`.trim().replace(/\s+/g, " ");
   const years = timeframe || (/\b202[0-9]\b/.test(base) ? "" : "2025 2026");
@@ -305,7 +300,6 @@ export function buildSearchRequests(claim: string, region = "", preferredSourceT
   return dedupeSearchRequests(requests);
 }
 
-/** Backward-compatible helper for callers/tests that need query text only. */
 export function buildSearchQueries(claim: string, region = "", preferredSourceType = "any", timeframe = ""): string[] {
   return buildSearchRequests(claim, region, preferredSourceType, timeframe).map((request) => request.query);
 }

From 5f2ce5cd1c20cf1c93cc59043d8049b57a56f788 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:52:17 +0200
Subject: [PATCH 77/84] test: lock current Exa contents request shape

---
 src/test/import-source-egress.test.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/test/import-source-egress.test.ts b/src/test/import-source-egress.test.ts
index d3356f14b..22085d74c 100644
--- a/src/test/import-source-egress.test.ts
+++ b/src/test/import-source-egress.test.ts
@@ -18,4 +18,9 @@ describe('import-source egress boundary', () => {
   it('keeps provider response consumption byte- and time-bounded', () => {
     expect(source).toContain('readBoundedText(response, EXA_RESPONSE_BYTES, FETCH_TIMEOUT_MS)');
   });
+
+  it('uses the current Exa text limit field name', () => {
+    expect(source).toContain('text: { maxCharacters: MAX_CONTENT_CHARS }');
+    expect(source).not.toContain('max_characters');
+  });
 });

From 18b120c49baef546f1daa98a11b2768fc41be55d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:52:36 +0200
Subject: [PATCH 78/84] docs: close search quality implementation plan

---
 plans/search-quality.md | 98 ++++++++++++++++++++---------------------
 1 file changed, 47 insertions(+), 51 deletions(-)

diff --git a/plans/search-quality.md b/plans/search-quality.md
index e11af3e59..421fe6779 100644
--- a/plans/search-quality.md
+++ b/plans/search-quality.md
@@ -1,56 +1,52 @@
-# Ask and Sitewide Search Quality Plan
+# Ask and Sitewide Search Quality — Completed Implementation Record
 
 ## Goal
 
 Make web research trustworthy across Generate, Attack, Brainstorm, Factoids, and Ask. Search should prefer specific, primary, current sources and visibly downgrade broad fallback sources.
 
-## Current Baseline
-
-- The shared Supabase `ai` function uses Exa for search and content extraction.
-- Search now runs multiple deterministic queries, AI follow-up queries, source ranking, and reads the strongest URLs first.
-- Ask displays source quality metadata in `searchInfo.sources`.
-
-## Next Implementation Steps
-
-1. Move research code from `supabase/functions/ai/index.ts` into `supabase/functions/_shared/research.ts`.
-2. Add topic-specific query builders:
-   - debate tournament: official pages, Tabbycat, Calicotab, WSDC, WUDC, tab/results pages.
-   - policy/statistics: government, intergovernmental orgs, academic papers, high-quality news.
-   - legal/current events: official laws, court pages, agencies, primary reporting.
-3. Add source quality metadata to all discovered source returns, not only Ask.
-4. Add source display components for Generate, Attack, Brainstorm, and Factoids where useful.
-5. Store source ranking metadata in saved source records so users can review why a source was selected.
-6. Add a "source quality floor":
-   - strong/moderate sources can support citations.
-   - weak sources can only appear as fallback context with an uncertainty.
-7. Add integration tests with mocked Exa responses for each feature.
-
-## Tests
-
-- Deno tests for ranking and query building.
-- Mocked edge function tests for Ask citation fallback.
-- Frontend tests for displaying source quality labels.
-- Manual browser test with current tournament queries and policy-stat queries.
-
-## Deployment
-
-Deploy `supabase functions deploy ai --project-ref uziwdtkzofptihahfooo` after Deno checks, frontend tests, and a local authenticated Ask test pass.
-
-## Status after Quality & Truth Release (branch t3code/quality-truth-release)
-
-Implemented:
-
-1. Research pipeline extracted to `supabase/functions/_shared/research.ts` (Exa search, follow-ups, ranking context, citation sources) with an injected model caller so it is testable; ranking/query builders moved to `_shared/source-quality.ts`.
-2. Topic-specific query builders (tournament, policy/statistics, legal/current events) were already present and are now covered by tests in the shared module.
-3. All discovered-source returns carry quality metadata; Factoids now also returns `discoveredSources`.
-4. Source display: shared `SourceQualityList` renders strong/moderate/weak labels plus "fallback context only" for weak sources in Generate, Attack, and Brainstorm results. Factoids shows only verified citations (quality-labeled consulted-list display deferred).
-5. Provenance persists to saved sources: `sources.metadata` jsonb (migration `20260822000001`, prepared but NOT applied) stores url, sourceType, qualityScore, qualityLabel, originating query, capturedVia.
-6. Source-quality floor completed: factoid citations verify only against fetched non-weak research content (`applyFactoidsVerification`); weak or unknown URLs are downgraded and filtered. Ask fallback already excluded weak sources.
-
-Tests: `_shared/research.test.ts`, extended `source-quality.test.ts`, frontend `SourceQualityList.test.tsx`, session-store provenance round-trip, client discoveredSources tests.
-
-Deferred:
-
-- Replace inline `site:gov` query text with Exa's dedicated domain-filter request field (needs a live Exa parameter-verification pass).
-- Handler-level integration test that mocks Exa end-to-end through `Deno.serve`; current coverage is at the extracted-function level plus frontend mocks.
-- Factoids UI panel listing all consulted sources with quality chips.
+## Completed source work
+
+1. Research is isolated in `supabase/functions/_shared/research.ts`, with model calls injected through `ResearchDeps` so the research layer remains testable.
+2. Topic-aware request planning covers:
+   - debate tournaments: official/tab/results searches, Tabbycat/Calicotab/WSDC/WUDC terminology;
+   - policy/statistics: government and intergovernmental data, academic evidence, current reporting;
+   - legal/current events: official laws, courts, agencies, primary sources.
+3. Preferred Exa source types are represented as first-class request fields rather than query-operator hacks:
+   - government/public-sector searches use `includeDomains` with a curated domain set;
+   - academic searches use Exa's `research paper` category;
+   - news searches use Exa's `news` category;
+   - a zero-result filtered request retries the same query without the filter to preserve recall.
+4. Search results are ranked with source type, quality score, quality label, reasons, query provenance, recency, specificity, and fallback penalties.
+5. Strong/moderate sources may support citations. Weak sources remain fallback context only.
+6. Generate, Attack, and Brainstorm expose researched source quality through the shared `SourceQualityList`.
+7. Factoids now returns `discoveredSources` separately from verified factoids and renders all consulted pages with quality chips. Weak consulted sources remain visible as fallback context but cannot become verified evidence.
+8. Ask keeps search metadata and citation fallback quality-gated.
+9. Saved source provenance can store source type, quality score/label, originating query, and capture path where the database migration is available.
+
+## Verification in source
+
+Coverage now includes:
+
+- ranking and topic-specific request planning;
+- raw Exa request body assertions for `includeDomains`, category, `numResults`, and text-size fields;
+- filtered-search zero-recall fallback;
+- quality-floor enforcement for Factoids;
+- frontend consulted-source labels and weak-source warnings;
+- Factoids client provenance parsing;
+- a handler-boundary Factoids test that imports the actual `supabase/functions/ai/index.ts` entrypoint through the Vitest `Deno.serve` loopback shim while mocking Supabase, Exa, and model-provider network boundaries.
+
+Relevant tests include:
+
+- `supabase/functions/_shared/research.test.ts`
+- `supabase/functions/_shared/research-exa-filters.test.ts`
+- `supabase/functions/ai/source-quality.test.ts`
+- `supabase/functions/ai/handler-research.test.ts`
+- `src/test/components/SourceQualityList.test.tsx`
+- `src/test/components/FactoidsResults.test.tsx`
+- `src/test/ai/factoids-provenance.test.ts`
+
+## Deployment status
+
+This record describes repository source. On `feature/sparring-verification-retention-loop`, **no Supabase migration or Edge Function has been applied or deployed**. Any backend behavior changed on this branch remains pending explicit deployment authorization.
+
+`supabase/migrations/20260822000001_source_provenance_metadata.sql` and any later branch migrations are source artifacts until separately applied.

From 31875443da60541260ff81544ea4ad83cf6f7928 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:52:57 +0200
Subject: [PATCH 79/84] chore: track agent and security review docs

---
 .gitignore | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index aefdf2aa9..4a594fa00 100644
--- a/.gitignore
+++ b/.gitignore
@@ -58,14 +58,16 @@ deno.lock
 tasks.txt
 humanizer.md
 
-# Local notes/docs, except the project README
+# Local notes/docs, except project-maintained records
 *.md
 *.txt
 *.info
 !README.md
+!AGENTS.md
 !**/README.md
 !docs/pricing-snapshots/*.md
 !plans/**/*.md
+!security/reviews/*.md
 .vercel
 .env*
 .worktrees/

From ea86c3a6a8d28017966b65995d6b5ed613a04296 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:53:32 +0200
Subject: [PATCH 80/84] security: record post-remediation source validation

---
 ...026-08-27-post-remediation-and-sparring.md | 117 ++++++++++++++++++
 1 file changed, 117 insertions(+)
 create mode 100644 security/reviews/2026-08-27-post-remediation-and-sparring.md

diff --git a/security/reviews/2026-08-27-post-remediation-and-sparring.md b/security/reviews/2026-08-27-post-remediation-and-sparring.md
new file mode 100644
index 000000000..ae48351df
--- /dev/null
+++ b/security/reviews/2026-08-27-post-remediation-and-sparring.md
@@ -0,0 +1,117 @@
+# Post-remediation source validation — 2026-08-27
+
+## Scope and limitations
+
+This is a source-backed validation record for the repository state on `feature/sparring-verification-retention-loop`. It is **not** a new Codex Security scanner result and it is **not** a live penetration test of staging or production.
+
+The baseline is the committed 2026-08-19 Codex Security scan (`security/scans/2026-08-19-codex-security-06d93a47`), which reported 11 findings: 2 high, 8 medium, and 1 low.
+
+The user explicitly prohibited applying migrations, deploying Edge Functions, setting Supabase secrets, or otherwise mutating staging/production Supabase during this branch. Therefore:
+
+- database-policy conclusions below are based on migration/function/client source;
+- branch migrations are **unapplied**;
+- branch Edge Function changes are **undeployed**;
+- no claim is made that staging or production currently contains branch-only backend fixes;
+- the opt-in stateful staging E2E suite was prepared but not executed.
+
+## Original August findings
+
+| # | Original finding | Source status | Evidence / note |
+|---|---|---|---|
+| 1 | Users can self-assign paid entitlements and restore expired trials | **Remediated in existing source** | `20260819000000_security_hardening.sql` revokes authenticated INSERT/DELETE and unrestricted UPDATE on `user_settings`, grants only preference-column updates, and AI entitlement readers fail closed for a missing settings row. |
+| 2 | Users can delete or forge the usage ledger that enforces AI quotas | **Remediated in existing source** | The hardening migration removes client writes to `ai_requests` and introduces the service-role-only atomic `consume_daily_quota` RPC. |
+| 3 | Anonymous users can enumerate all active shared items | **Remediated in existing source** | Public table SELECT is removed; `get_shared_item(p_share_code)` exposes only a possessed, non-expired capability and updates its view count atomically. `SharedPage` calls this RPC. |
+| 4 | Anonymous callers can create arbitrary shared items | **Remediated in existing source** | Direct anon/authenticated access to `shared_items` is revoked; the `share` Edge Function requires a valid user before inserting and generates share codes server-side. |
+| 5 | SECURITY DEFINER analytics functions are exposed too broadly | **Remediated in existing source** | Sensitive analytics RPCs call `require_admin()`. `20260820090000_advisor_security_cleanup.sql` revokes public/anon/authenticated execution from internal SECURITY DEFINER helpers as appropriate. |
+| 6 | Promo redemption accepts a caller-selected beneficiary | **Remediated in existing source** | The UUID-taking RPC is dropped. `redeem_promo_code_atomic(text)` derives `v_user_id := auth.uid()`, and the Edge Function invokes it through the caller-authenticated client. |
+| 7 | Source importer can be DNS-rebound into private network targets | **Remediated on this branch, not deployed** | `import-source` no longer performs a network request to the user-controlled hostname. The validated URL is sent as data to the fixed `https://api.exa.ai/contents` egress endpoint. Tests assert the importer has exactly one executable fetch destination. |
+| 8 | Citation verification performs blind requests to model-provided URLs | **Remediated in existing source** | `_shared/research.ts::verifyUrl` deliberately performs no network request to model-provided citation URLs; unsupported verification remains explicitly false. |
+| 9 | Source importer can consume an unbounded/slow response body after headers | **Remediated on this branch, not deployed** | `readBoundedText` enforces both a 1 MB byte cap and a body-read deadline, including streamed bodies whose headers already arrived. The fixed Exa egress response is consumed through this helper. |
+| 10 | Concurrent requests can race past the daily quota | **Remediated in existing source; correctness strengthened on this branch** | Existing source uses service-role-only atomic UPSERT reservation. This branch additionally scopes counters by `quota_key` so source imports cannot consume the independently configured AI allowance. The scoping migration is unapplied. |
+| 11 | Unknown model IDs can bypass Pro-model gating / provider assumptions | **Remediated in existing source** | `MODEL_PROVIDERS` is a positive allowlist and `providerForModel` rejects unsupported model/provider combinations before provider work. |
+
+## Branch-specific security findings and fixes
+
+### 1. Cross-account exposure of locally persisted Sparring transcripts
+
+**Finding:** Sparring sessions were persisted in browser storage but initially were not cleared on sign-out or account changes. A second user on the same browser profile could inherit the previous account's local practice transcripts.
+
+**Fix:** `AuthProvider` now clears `useSparringStore` when:
+
+- the session becomes unauthenticated;
+- the authenticated user ID changes;
+- explicit sign-out runs.
+
+`src/test/stores/sparring-store.test.ts` covers the clearing operation.
+
+### 2. Untrusted persisted Sparring state
+
+**Finding:** browser-persisted session data is user-controlled and could contain malformed shapes.
+
+**Fix:** the persisted session list is re-parsed through `SparringSessionSchema`; malformed entries are dropped and `activeSessionId` is retained only when it references a validated session.
+
+### 3. Dishonest source-grounding control
+
+**Finding:** an early Sparring UI revision exposed a per-round “Use active sources” switch while the shared AI client always attached active Source Library items. Turning the switch off would not have changed the request.
+
+**Fix:** the false OFF control was removed. Sparring now states that active Source Library items are factual grounding and links users to the Library to manage that selection.
+
+### 4. Preference persistence conflicted with the entitlement hardening model
+
+**Finding:** the browser settings store still used `upsert`, which requires INSERT privilege even on conflict, while the security hardening migration intentionally revoked authenticated INSERT on `user_settings`. In addition, `output_language` was omitted from the allowed preference-column UPDATE grant.
+
+**Fix in branch source:** 
+
+- settings persistence now performs UPDATE on the already-provisioned row, scoped to the current user;
+- `20260827000000_user_settings_output_language_privilege.sql` grants UPDATE on only `output_language` to authenticated users.
+
+**Deployment status:** the migration is unapplied, so deployed environments do not gain this branch-only privilege until separately authorized.
+
+### 5. Import quota and AI quota shared one counter namespace
+
+**Finding:** the atomic counter removed the race condition, but `daily_usage_counters` had only `(user_id, usage_date)`. Import requests and normal AI requests have different configured limits yet incremented the same row, causing one workload to consume the other's allowance.
+
+**Fix in branch source:** `20260827001000_scope_daily_usage_counters.sql` adds `quota_key`, changes the primary key to `(user_id, usage_date, quota_key)`, gives existing two-argument callers a default `ai` namespace, and makes the importer pass `import_source`.
+
+**Deployment status:** unapplied.
+
+## Search / provenance trust-boundary changes reviewed
+
+The branch closes the previously deferred Search Quality work:
+
+- Exa government/public-sector restrictions are request `includeDomains` fields rather than `site:` query text.
+- Academic and news preferences use Exa category fields.
+- Filtered zero-result searches retry unfiltered to avoid silent recall collapse.
+- Factoids preserves consulted-source provenance separately from verified evidence.
+- Weak consulted sources remain visible as fallback context but cannot become verified Factoids evidence.
+- A handler-boundary test imports the actual `supabase/functions/ai/index.ts` entrypoint under loopback shims and mocks Supabase/Exa/model network boundaries.
+
+The source importer is also aligned to a fixed Exa egress boundary and bounded provider-response consumption.
+
+## Verification artifacts added
+
+Security-relevant regression coverage includes:
+
+- `src/test/security-hardening.test.ts`
+- `src/test/import-source-egress.test.ts`
+- `supabase/functions/import-source/resource-limits.test.ts`
+- `supabase/functions/import-source/url-validation.test.ts`
+- `supabase/functions/_shared/research-exa-filters.test.ts`
+- `supabase/functions/ai/source-quality.test.ts`
+- `supabase/functions/ai/handler-research.test.ts`
+- `src/test/stores/sparring-store.test.ts`
+- `src/test/ai/factoids-provenance.test.ts`
+- deterministic Playwright Sparring flow/recovery tests.
+
+## Remaining uncertainty before deployment
+
+The branch should not be described as production-remediated until the following occur under explicit authorization:
+
+1. run the full repository verification gate successfully;
+2. review/apply the branch migrations in a controlled environment;
+3. deploy the changed Edge Functions;
+4. run the stateful authenticated staging suite;
+5. validate effective RLS/GRANT/RPC privileges against the actual remote database;
+6. run a fresh official security scan against the deployment candidate.
+
+Until then, branch-only backend remediations are repository source, not active Supabase controls.

From 38b97faf453a07e754b2eb09b5284d38af4d64d1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:53:53 +0200
Subject: [PATCH 81/84] docs: mark branch implementation phase complete

---
 plans/README.md | 35 +++++++++++++++++++++++------------
 1 file changed, 23 insertions(+), 12 deletions(-)

diff --git a/plans/README.md b/plans/README.md
index 110278a8d..2c8972fcb 100644
--- a/plans/README.md
+++ b/plans/README.md
@@ -2,36 +2,47 @@
 
 This folder tracks remaining DebateLab product work. The source tree is the authority: a plan is active only when it describes work that is not already present on the current branch.
 
-## NOW
+## Current branch status
 
-1. **Sparring v1** — turn DebateLab from a preparation toolbox into a repeatable training loop: motion → side → opponent exchange → qualitative scorecard → targeted next drill.
-2. **Verification loop** — keep PR CI deterministic, add browser coverage for the critical product journeys, and prepare authenticated staging E2E without applying or deploying any Supabase changes from this branch.
-3. **Post-remediation security validation** — verify the August security findings against current source and add regression tests around the remediated trust boundaries.
+`feature/sparring-verification-retention-loop` implements the planned product/verification source work:
 
-## NEXT
+- Sparring v1: four-speech practice loop, transcript-grounded qualitative scorecard, retry recovery, local history, exports, analytics, and handoffs into Ask/Attack/Brainstorm/Factoids.
+- Verification loop: one `npm run verify` gate covering lint, typecheck, coverage, build, and deterministic Playwright browser journeys with retained failure evidence.
+- Authenticated staging E2E: prepared as a separate opt-in stateful suite, deliberately excluded from PR CI and not executed while remote Supabase mutation is prohibited.
+- Post-remediation security validation: original August findings mapped to current source, regression tests strengthened, and branch-only backend hardening recorded under `security/reviews/`.
+- Search Quality: first-class Exa domain/category filters, raw request tests, handler-boundary research coverage, and Factoids consulted-source provenance/UI are implemented in source.
 
-- [Ask and sitewide search quality](./search-quality.md): finish the remaining Exa domain-filter verification, handler-level integration coverage, and Factoids consulted-source UI.
-- Sparring follow-ups driven by product data: format presets, richer drills, voice/live-round experiments, and longitudinal progress only after the core loop proves useful.
-- Conversion and retention work based on measured activation and repeat usage.
+No branch migration or Edge Function has been applied/deployed to Supabase.
+
+## NEXT — data and authorized deployment, not another feature pile
+
+- Run the full verification gate on an available runner and fix any executed failures.
+- When explicitly authorized, review/apply the pending Supabase migrations and deploy changed functions to a controlled staging environment, then execute the separate stateful staging suite.
+- Run a fresh official security scan against the deployment candidate after those backend changes are actually active.
+- Measure Sparring activation, completion, rematch/revisit behavior, feedback-action usage, and conversion before expanding the training product.
+- Choose follow-up Sparring work from evidence: format presets, richer drills, voice/live-round experiments, and longitudinal progress only if the core loop proves useful.
+- Conversion/retention work should follow observed funnel behavior rather than assumed feature demand.
 
 ## LATER
 
 - [Admin announcements](./admin-announcements.md)
 - [Animation polish](./animation-polish.md)
 - [Rate-limit UI cleanup](./rate-limit-ui-cleanup.md)
-- Further model/prompt experiments that are supported by evaluation data.
+- Further model/prompt experiments supported by evaluation data.
 
 ## Historical / substantially implemented
 
 These files are kept for implementation history. Do not treat them as current instructions without checking the source tree first.
 
+- [Ask and sitewide search quality](./search-quality.md) — implementation record; formerly deferred domain filtering, handler coverage, and Factoids consulted-source UI are now present on this branch.
 - [Streaming AI](./streaming-ai.md) — Ask streaming endpoint/client/tests are already present.
-- [Source auto-import](./source-auto-import.md) — import endpoint, validation, schema, Library integration, and tests are already present.
+- [Source auto-import](./source-auto-import.md) — import endpoint, validation, schema, Library integration, and tests are present; this branch further hardens its network egress in source.
 - [Control honesty and deterministic toggles](./control-honesty.md) — core enforcement is implemented and tested.
+- [Debate sparring and streaming](./sparring-and-streaming.md) — original design record; Sparring v1 is implemented with a deliberately narrower four-speech loop.
 - [Model cost accounting](./model-cost-accounting.md) — accounting helpers, audit metadata, and tests are present; remaining work is operational validation.
 - [System prompt improvement](./system-prompt-improvement.md) — layered shared prompt architecture is present.
-- [Quality & Truth release checklist](./release-checklist.md) — use as a release-history checklist, not a live roadmap.
-- [Supabase staging](./supabase-staging.md) and [Agent verification loop](./agent-verification-loop.md) — still useful design references, but any migration/function/secret deployment is explicitly out of scope for this feature branch.
+- [Quality & Truth release checklist](./release-checklist.md) — use as release history/checklist, not a live roadmap.
+- [Supabase staging](./supabase-staging.md) and [Agent verification loop](./agent-verification-loop.md) — useful design references, but migration/function/secret deployment is explicitly outside the current branch execution boundary.
 
 ## Done
 

From eac91c707b176052afcef48bc62c2c2bae80e140 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 00:56:51 +0200
Subject: [PATCH 82/84] test: avoid source-filter reference-equality
 assumptions

---
 supabase/functions/ai/source-quality.test.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/supabase/functions/ai/source-quality.test.ts b/supabase/functions/ai/source-quality.test.ts
index d425b516a..4fe2fc66a 100644
--- a/supabase/functions/ai/source-quality.test.ts
+++ b/supabase/functions/ai/source-quality.test.ts
@@ -74,7 +74,8 @@ Deno.test("government preference uses Exa includeDomains instead of site query s
   const filtered = requests.find((request) => request.includeDomains?.length);
   assert(Boolean(filtered), `Expected a domain-filtered government request, got ${JSON.stringify(requests)}`);
   assert(filtered!.includeDomains!.includes("energy.gov"), "Expected energy.gov in government domain set");
-  assert(filtered!.includeDomains === GOVERNMENT_SEARCH_DOMAINS, "Expected canonical government domain list");
+  assert(filtered!.includeDomains!.length === GOVERNMENT_SEARCH_DOMAINS.length, "Expected canonical government domain list length");
+  assert(GOVERNMENT_SEARCH_DOMAINS.every((domain) => filtered!.includeDomains!.includes(domain)), "Expected canonical government domains");
   assert(requests.every((request) => !/\bsite:/i.test(request.query)), "site: operator must not leak into Exa query text");
 });
 

From 52c422464a85ecb470df99b7227fcea81696f751 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 01:05:05 +0200
Subject: [PATCH 83/84] fix: avoid duplicating sparring Ask handoff prompt

---
 src/pages/SparringPage.tsx | 46 +++++++++++++++++++++++++++++++-------
 1 file changed, 38 insertions(+), 8 deletions(-)

diff --git a/src/pages/SparringPage.tsx b/src/pages/SparringPage.tsx
index 51a4464e1..9b5d0b427 100644
--- a/src/pages/SparringPage.tsx
+++ b/src/pages/SparringPage.tsx
@@ -23,7 +23,9 @@ import { useSubscriptionError } from '@/hooks/use-subscription-error';
 import { useToast } from '@/hooks/use-toast';
 
 function transcriptText(turns: SparringTurn[]) {
-  return turns.map((turn, index) => `${index + 1}. ${turn.role === 'user' ? 'You' : 'AI opponent'} (${turn.phase}): ${turn.content}`).join('\n\n');
+  return turns
+    .map((turn, index) => `${index + 1}. ${turn.role === 'user' ? 'You' : 'AI opponent'} (${turn.phase}): ${turn.content}`)
+    .join('\n\n');
 }
 
 function userAdvocacyText(turns: SparringTurn[]) {
@@ -39,12 +41,14 @@ export default function SparringPage() {
   const subError = useSubscriptionError();
   const config = useSettingsStore((state) => state.getFeatureConfig('sparring'));
   const askConfig = useSettingsStore((state) => state.getFeatureConfig('ask'));
+
   const sessions = useSparringStore((state) => state.sessions);
   const activeSessionId = useSparringStore((state) => state.activeSessionId);
   const startSession = useSparringStore((state) => state.startSession);
   const addTurn = useSparringStore((state) => state.addTurn);
   const completeSession = useSparringStore((state) => state.completeSession);
   const setActiveSession = useSparringStore((state) => state.setActiveSession);
+
   const activeSourceCount = useSessionStore((state) => state.sourceLibrary.filter((source) => source.isActive).length);
   const {
     addAskMessage,
@@ -54,6 +58,7 @@ export default function SparringPage() {
     setBrainstormForm,
     setFactoidsForm,
   } = useSessionStore();
+
   const [isThinking, setIsThinking] = useState(false);
   const [isScoring, setIsScoring] = useState(false);
   const [pressurePoints, setPressurePoints] = useState<string[]>([]);
@@ -84,6 +89,7 @@ export default function SparringPage() {
 
   const handleSubmitSpeech = async (content: string, phase: SparringTurnPhase) => {
     if (!session || isThinking) return;
+
     addTurn(session.id, { role: 'user', phase, content });
     captureProductEvent(phase === 'opening' ? 'sparring_opening_submitted' : 'sparring_turn_completed', {
       phase,
@@ -116,9 +122,11 @@ export default function SparringPage() {
     if (!session || isThinking) return;
     const current = getSparringSession(session.id);
     if (!current) return;
+
     const userTurns = current.turns.filter((turn) => turn.role === 'user');
     const aiTurns = current.turns.filter((turn) => turn.role === 'ai');
     if (userTurns.length !== aiTurns.length + 1) return;
+
     const latestUserTurn = [...current.turns].reverse().find((turn) => turn.role === 'user');
     if (!latestUserTurn) return;
 
@@ -143,7 +151,11 @@ export default function SparringPage() {
   const handleFinish = async () => {
     if (!session || isScoring) return;
     const current = getSparringSession(session.id);
-    if (!current || current.turns.filter((turn) => turn.role === 'user').length < 2 || current.turns.filter((turn) => turn.role === 'ai').length < 2) return;
+    if (!current) return;
+
+    const userTurns = current.turns.filter((turn) => turn.role === 'user').length;
+    const aiTurns = current.turns.filter((turn) => turn.role === 'ai').length;
+    if (userTurns < 2 || aiTurns < 2) return;
 
     setIsScoring(true);
     try {
@@ -175,14 +187,18 @@ export default function SparringPage() {
 
   const handleDiscuss = async () => {
     if (!session?.scorecard) return;
+
     const prompt = `I just finished a DebateLab sparring round and want to improve it.\n\nMotion: ${session.setup.motion}\nMy side: ${session.setup.side}\nVerdict: ${session.scorecard.verdict}\nBiggest improvement: ${session.scorecard.biggestImprovement}\nNext drill: ${session.scorecard.nextDrill}\n\nTranscript:\n${transcriptText(session.turns)}\n\nHelp me turn this feedback into a concrete improvement plan. Focus on the actual transcript.`;
 
+    // Persist the visible handoff once, then pass only the pre-existing chat as
+    // history. askChat appends `prompt` as the current user message itself.
     addAskMessage({ role: 'user', content: prompt });
     navigate('/app/ask');
     captureProductEvent('sparring_feedback_action_used', { action: 'discuss_in_ask' });
     setAskLoading(true);
+
     try {
-      const history = [...askMessages, { role: 'user' as const, content: prompt }].map((message) => ({
+      const history = askMessages.map((message) => ({
         role: message.role as 'user' | 'assistant',
         content: message.content,
       }));
@@ -226,6 +242,7 @@ export default function SparringPage() {
     if (!session) return;
     const opening = session.turns.find((turn) => turn.role === 'user' && turn.phase === 'opening');
     if (!opening) return;
+
     setFactoidsForm({
       claim: opening.content,
       direction: 'for',
@@ -329,7 +346,10 @@ export default function SparringPage() {
               <AnimatedSection delay={100} className="mt-8">
                 <Card className="border-border/70 bg-card/60">
                   <CardHeader className="pb-3">
-                    <CardTitle className="flex items-center gap-2 text-base"><History className="h-4 w-4 text-primary" />Recent sparring rounds</CardTitle>
+                    <CardTitle className="flex items-center gap-2 text-base">
+                      <History className="h-4 w-4 text-primary" />
+                      Recent sparring rounds
+                    </CardTitle>
                   </CardHeader>
                   <CardContent className="space-y-2">
                     {recentCompleted.map((item) => (
@@ -343,10 +363,14 @@ export default function SparringPage() {
                           <div className="truncate text-sm font-medium">{item.setup.motion}</div>
                           <div className="mt-1 text-xs text-muted-foreground">{new Date(item.createdAt).toLocaleString()}</div>
                         </div>
-                        <Badge variant="outline" className="shrink-0 capitalize">{item.scorecard?.verdict.replace('-', ' ')}</Badge>
+                        <Badge variant="outline" className="shrink-0 capitalize">
+                          {item.scorecard?.verdict.replace('-', ' ')}
+                        </Badge>
                       </button>
                     ))}
-                    <Button variant="ghost" size="sm" onClick={() => navigate('/app/history')}>Open full history</Button>
+                    <Button variant="ghost" size="sm" onClick={() => navigate('/app/history')}>
+                      Open full history
+                    </Button>
                   </CardContent>
                 </Card>
               </AnimatedSection>
@@ -361,12 +385,18 @@ export default function SparringPage() {
         variant={subError.limitModalVariant}
         limit={subError.limitModalLimit}
         current={subError.limitModalCurrent}
-        onUpgrade={() => { subError.setLimitModalOpen(false); subError.setPricingModalOpen(true); }}
+        onUpgrade={() => {
+          subError.setLimitModalOpen(false);
+          subError.setPricingModalOpen(true);
+        }}
       />
       <ModelRestrictedModal
         open={subError.modelModalOpen}
         onOpenChange={subError.setModelModalOpen}
-        onUpgrade={() => { subError.setModelModalOpen(false); subError.setPricingModalOpen(true); }}
+        onUpgrade={() => {
+          subError.setModelModalOpen(false);
+          subError.setPricingModalOpen(true);
+        }}
       />
       <PricingModal open={subError.pricingModalOpen} onOpenChange={subError.setPricingModalOpen} />
     </div>

From 10d5a956137099c9b37b2f11f86054eda2545784 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81d=C3=A1m=20G=C3=A1borj=C3=A1ni-Szab=C3=B3?=
 <117768520+Programcode@users.noreply.github.com>
Date: Thu, 27 Aug 2026 01:05:46 +0200
Subject: [PATCH 84/84] test: verify sparring Ask handoff history

---
 e2e/sparring-flow.spec.ts | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/e2e/sparring-flow.spec.ts b/e2e/sparring-flow.spec.ts
index 6df865c96..fe8947868 100644
--- a/e2e/sparring-flow.spec.ts
+++ b/e2e/sparring-flow.spec.ts
@@ -35,8 +35,10 @@ test.beforeEach(async ({ page }) => {
   await stubSupabaseSession(page);
 });
 
-test('sparring completes a deterministic training loop and hands the round to Attack', async ({ page }) => {
+test('sparring completes the training loop and hands the round into existing tools', async ({ page }) => {
   let aiCall = 0;
+  let discussInput: { message?: string; history?: Array<{ role?: string; content?: string }> } | undefined;
+
   await page.route('**/functions/v1/ai', async (route) => {
     if (route.request().method() === 'OPTIONS') {
       await route.fulfill({ status: 200, headers: corsHeaders, body: 'ok' });
@@ -44,6 +46,17 @@ test('sparring completes a deterministic training loop and hands the round to At
     }
 
     aiCall += 1;
+    if (aiCall === 4) {
+      const requestBody = route.request().postDataJSON() as { input?: typeof discussInput };
+      discussInput = requestBody.input;
+      await route.fulfill({
+        status: 200,
+        headers: corsHeaders,
+        body: askEnvelope('Focus the next drill on comparing universal access against targeted alternatives.'),
+      });
+      return;
+    }
+
     const response = aiCall === 1
       ? JSON.stringify({
           speech: 'A universal free-transit policy is expensive. Targeted discounts can improve access while preserving funding for service quality.',
@@ -83,8 +96,16 @@ test('sparring completes a deterministic training loop and hands the round to At
 
   await page.getByRole('button', { name: 'Attack my round' }).click();
   await expect(page).toHaveURL(/\/app\/attack$/);
-  await expect(page.locator('#caseText')).toContainText('');
   await expect(page.locator('#caseText')).toHaveValue(new RegExp(opening.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+
+  await page.goto('/app/sparring');
+  await page.getByRole('button', { name: 'Discuss with Ask' }).click();
+  await expect(page).toHaveURL(/\/app\/ask$/);
+  await expect(page.getByText(/Focus the next drill on comparing universal access/i)).toBeVisible();
+
+  expect(discussInput?.message).toContain('I just finished a DebateLab sparring round');
+  expect(discussInput?.history?.some((entry) => entry.content === discussInput?.message)).toBe(false);
+  expect(aiCall).toBe(4);
 });
 
 test('sparring can retry a failed opponent response without losing the user speech', async ({ page }) => {