fix(chat): render footnote citations under a single Sources header (#987)

### What this fixes

Follow-up to #981. On the reported chat (`57493241`, dashboard) the
agentic reply showed **two headings** ("Sources" and "Footnotes"), the
**superscript citation links gave no feedback** when clicked, and every
source line stacked **several arrow icons** (the external-link arrow
plus one ↩ back-reference per citation).

### Why it happened

- The prompt told the model to write a literal "Sources" header above
its footnote definitions. remark-gfm then moves the definitions into its
own trailing section headed "Footnotes", so the model's header stays
behind as an empty duplicate.
- The renderer's "Footnotes" heading ships with an `sr-only` class,
which our Tailwind build never generates (no source file uses it), so
the heading that is meant to be invisible is visible.
- The superscripts use fragment navigation. Every message mints the same
ids (`#user-content-fn-1`), a repeated click on the same fragment does
nothing, and when the footnote list is already on screen (the exact case
in the reported chat, verified against the stored row in prod) nothing
visibly happens at all.

### What changed

- `Markdown.tsx` takes an optional footnote label and id prefix and
passes them through remark-rehype: the section heading is ours now
(visible, localised) and footnote ids are unique per message. Surfaces
that pass no label keep the default "Footnotes" heading but hidden
behind `dembrane-sr-only`, a visually-hidden class we define ourselves
in `index.css` (our own name so it cannot collide with Tailwind's
`sr-only` utility).
- `ChatHistoryMessage.tsx` passes `Sources` (per locale, `Bronnen` in
Dutch, other catalogs fall back to English until translated) plus a
per-message id prefix. A superscript click scrolls to the source line
and flashes it with the same cyan highlight the transcript page uses for
a deep-linked chunk — feedback even when the target was already on
screen, no URL rewrite, no history entries. The ↩ back-references are
dropped in agentic chat: one icon per source line.
- `agent.py` no longer asks the model for a header above the
definitions; the renderer owns the heading. Prompt test updated to pin
this.

### Already-persisted rows

Exactly one row in all of production stores the old model-written header
(verified by query): the beta test chat this was reported on. Agentic
chat is beta; the row stays as is. No migration, no render-time
compatibility code.

### Tests

- `AgenticChatPanel.test.tsx`: 15 passed, including a new case pinning
that footnote definition tags become rich transcript links.
- `agent/tests/test_agent_tools.py`: 65 passed.
- `tsc --noEmit` and `biome lint` clean; end-to-end renders verified:
one "Sources" heading in chat, hidden "Footnotes" heading on label-less
surfaces, unique prefixed ids.

Discussion:
https://dembraneworkspace.slack.com/archives/C0884QPQF6W/p1786381186184369

Author: spashii

echo/agent/agent.py

@@ -319,11 +319,11 @@ def _rename_tool_name(name: str) -> str:
 ## Citations
 - Ground every claim about the project in tool results.
 - To keep the response clean, never put raw conversation citation tags directly inline in your main text. Instead, use standard Markdown footnote superscript tags (like [^1], [^2]) inline where you cite a source.
-- At the very end of your response, list all cited sources under a "Sources" header as footnote definitions. Group multiple citations of the same conversation or chunk into a single unique footnote entry to avoid clutter.
+- At the very end of your response, list the footnote definitions. Do not write any header above them (no "Sources", no "Footnotes"): the app renders the footnote list under its own localized sources header, so a header from you shows up as a duplicate. Group multiple citations of the same conversation or chunk into a single unique footnote entry to avoid clutter.
 - Each footnote definition at the bottom must carry the exact citation tag in the format `[^1]: [conversation_id:<id>;chunk_id:<chunk_id>]` when a chunk id is available, otherwise `[^1]: [conversation_id:<id>]`.
 - Quote with attribution inside your footnote definitions or inline text: "[Participant Name]: quoted text".
 - Keep footnote numbering sequential starting from 1 (e.g., [^1], [^2], [^3]). Every inline footnote tag must have exactly one corresponding footnote definition at the bottom.
-- If there are no claims to cite from the conversations, omit the footnotes and the "Sources" header entirely.
+- If there are no claims to cite from the conversations, omit the footnotes entirely.
 - A few well-chosen quotes beat many.
 - Cite the doc path when you answer from documentation.
 

echo/agent/tests/test_agent_tools.py

@@ -485,6 +485,9 @@ def test_system_prompt_contains_conversational_and_research_directives():
     assert "[conversation_id:<id>;chunk_id:<chunk_id>]" in SYSTEM_PROMPT
     assert "[conversation_id:<id>]" in SYSTEM_PROMPT
     assert "footnote" in prompt
+    # The frontend renders the footnote list under its own localized header;
+    # a model-written one duplicates it (ChatHistoryMessage.tsx)
+    assert "do not write any header above them" in prompt
     assert "worked from summaries only" in prompt
     assert "read the full transcript" in prompt
     assert "never fabricate quotes" in prompt

echo/frontend/src/components/chat/AgenticChatPanel.test.tsx

@@ -197,7 +197,7 @@ vi.mock("./ChatHistoryMessage", () => ({
 	),
 }));
 
-import { AgenticChatPanel } from "./AgenticChatPanel";
+import { AgenticChatPanel, enrichAgenticContent } from "./AgenticChatPanel";
 
 const at = (seq: number) =>
 	new Date(Date.UTC(2026, 7, 1, 10, seq)).toISOString();
@@ -650,3 +650,26 @@ describe("AgenticChatPanel, voice input", () => {
 		expect(screen.getByTestId("chat-input-textarea")).toBeTruthy();
 	});
 });
+
+describe("enrichAgenticContent, footnote citations", () => {
+	const CONVERSATION_ID = "0aa78d5a-1111-2222-3333-444455556666";
+
+	const enrich = (content: string) =>
+		enrichAgenticContent({
+			content,
+			conversationNames: new Map([[CONVERSATION_ID, "Maria"]]),
+			language: "en-US",
+			projectId: "project-1",
+			workspaceId: "workspace-1",
+		});
+
+	it("turns footnote definition tags into rich transcript links", () => {
+		const enriched = enrich(
+			`Parking came up often[^1].\n\n[^1]: [conversation_id:${CONVERSATION_ID};chunk_id:chunk-9]`,
+		);
+
+		expect(enriched).toContain("[^1]: [Maria's transcript excerpt](");
+		expect(enriched).toContain("#chunk-chunk-9");
+		expect(enriched).not.toContain("conversation_id:");
+	});
+});

echo/frontend/src/components/chat/AgenticChatPanel.tsx

@@ -246,7 +246,7 @@ const FocusedOnLine = ({
 	);
 };
 
-const enrichAgenticContent = ({
+export const enrichAgenticContent = ({
 	content,
 	conversationNames,
 	language,

echo/frontend/src/components/chat/ChatHistoryMessage.tsx

@@ -76,6 +76,26 @@ const getLinkLabel = (children: React.ReactNode) => {
 const AGENTIC_LINK_CLASSES =
 	"not-prose inline-flex items-baseline gap-0.5 text-[var(--mantine-color-anchor)] underline underline-offset-2 transition-colors hover:text-[var(--mantine-color-blue-7)]";
 
+// The same flash the transcript page gives a deep-linked chunk
+// (ConversationChunkAudioTranscript), so a footnote hop reads as the one
+// highlight language the product has. Class names must match ones already in
+// source, or the Tailwind build will not carry them.
+const FOOTNOTE_HIGHLIGHT_CLASSES = [
+	"!bg-cyan-50",
+	"ring-2",
+	"ring-cyan-300",
+	"rounded-sm",
+];
+const FOOTNOTE_HIGHLIGHT_MS = 5000;
+
+const flashFootnoteTarget = (target: HTMLElement) => {
+	target.scrollIntoView({ behavior: "smooth", block: "center" });
+	target.classList.add(...FOOTNOTE_HIGHLIGHT_CLASSES);
+	window.setTimeout(() => {
+		target.classList.remove(...FOOTNOTE_HIGHLIGHT_CLASSES);
+	}, FOOTNOTE_HIGHLIGHT_MS);
+};
+
 const URL_PATTERN = /https?:\/\/[^\s<>)\]]+/g;
 
 function ownPortalStartLink(content: string, projectId?: string): string | null {
@@ -216,6 +236,39 @@ export const ChatHistoryMessage = ({
 
 		return {
 			a({ children, className, href, ...props }) {
+				// The ↩ back-references under each footnote add a second (or Nth)
+				// arrow icon per source line without earning it: the superscript
+				// that brought the reader down is still on screen after the
+				// highlight scroll. One icon per source, so these go.
+				if (className?.includes("data-footnote-backref")) {
+					return null;
+				}
+
+				// Footnote hops (superscript -> definition) stay inside this
+				// message. Fragment navigation is the wrong tool for them in an
+				// SPA: it rewrites the URL, stacks history entries, a repeated
+				// click on the same fragment does not scroll again, and a target
+				// already on screen gives no feedback at all. So scroll and flash
+				// the target directly and leave the URL alone.
+				if (href?.startsWith("#")) {
+					return (
+						<a
+							href={href}
+							className={className}
+							{...props}
+							onClick={(event) => {
+								event.preventDefault();
+								const target = document.getElementById(
+									decodeURIComponent(href.slice(1)),
+								);
+								if (target) flashFootnoteTarget(target);
+							}}
+						>
+							{children}
+						</a>
+					);
+				}
+
 				if (isDocsHref(href)) {
 					return (
 						<AgenticDocsLink href={href ?? ""}>{children}</AgenticDocsLink>
@@ -333,6 +386,8 @@ export const ChatHistoryMessage = ({
 							className="prose-sm"
 							content={message.content}
 							components={markdownComponents}
+							footnoteLabel={t`Sources`}
+							footnoteIdPrefix={`msg-${message.id}-`}
 						/>
 						{portalStartLink ? (
 							<Box

echo/frontend/src/components/common/Markdown.tsx

@@ -13,10 +13,20 @@ export const Markdown = ({
 	content,
 	className,
 	components: customComponents,
+	footnoteLabel,
+	footnoteIdPrefix,
 }: {
 	content: string;
 	className?: string;
 	components?: Components;
+	/** Visible, localised heading for the GFM footnote list. Without it the
+	 * renderer's default English "Footnotes" heading is kept but visually
+	 * hidden (screen readers still announce it). */
+	footnoteLabel?: string;
+	/** Prefix for footnote ids and hrefs. Every message rendered on a page
+	 * otherwise mints the same `#user-content-fn-1` ids, so the browser
+	 * resolves a superscript to the first message that defined it. */
+	footnoteIdPrefix?: string;
 }) => {
 	// FIXME: workaround to load Tally embeds
 	useEffect(() => {
@@ -57,13 +67,28 @@ export const Markdown = ({
 		[customComponents],
 	);
 
+	const remarkRehypeOptions = useMemo(
+		() => ({
+			...(footnoteIdPrefix ? { clobberPrefix: footnoteIdPrefix } : {}),
+			// A caller who names the label wants it visible; without one, the
+			// renderer's default English "Footnotes" heading stays, hidden with
+			// our own class. The library's default is `sr-only`, which our
+			// Tailwind build never generates (no source file uses it).
+			...(footnoteLabel
+				? { footnoteLabel, footnoteLabelProperties: {} }
+				: { footnoteLabelProperties: { className: "dembrane-sr-only" } }),
+		}),
+		[footnoteLabel, footnoteIdPrefix],
+	);
+
 	return (
 		<ReactMarkdown
 			className={cn(
 				"prose prose-table:block prose-table:w-full prose-table:overflow-x-scroll",
 				className,
 			)}
 			remarkPlugins={[remarkGfm]}
+			remarkRehypeOptions={remarkRehypeOptions}
 			components={components}
 		>
 			{processedContent}

echo/frontend/src/index.css

@@ -98,6 +98,22 @@ body {
 	font-feature-settings: var(--app-font-feature-settings) !important;
 }
 
+/* Visually hidden, kept for screen readers. Our own name on purpose: Tailwind
+   owns `sr-only` and only generates it when a source file uses it, so markup
+   injected at runtime (the markdown renderer's footnote heading) needs a class
+   we define unconditionally. */
+.dembrane-sr-only {
+	position: absolute;
+	width: 1px;
+	height: 1px;
+	padding: 0;
+	margin: -1px;
+	overflow: hidden;
+	clip: rect(0, 0, 0, 0);
+	white-space: nowrap;
+	border-width: 0;
+}
+
 [aria-label="editable markdown"] {
 	font-family: var(--app-font-family) !important;
 	font-feature-settings: var(--app-font-feature-settings) !important;

echo/frontend/src/locales/cs-CZ.po

@@ -2528,7 +2528,7 @@ msgstr "Content"
 msgid "Context"
 msgstr "Context"
 
-#: src/components/chat/ChatHistoryMessage.tsx:394
+#: src/components/chat/ChatHistoryMessage.tsx:449
 msgid "Context added:"
 msgstr "Context added:"
 
@@ -3435,7 +3435,7 @@ msgstr "Do you want to stay in the loop?"
 
 #: src/features/sidebar/views/HelpView.tsx:36
 #: src/features/sidebar/blocks/HelpBlock.tsx:46
-#: src/components/chat/ChatHistoryMessage.tsx:172
+#: src/components/chat/ChatHistoryMessage.tsx:192
 msgid "Documentation"
 msgstr "Documentation"
 
@@ -4763,7 +4763,7 @@ msgstr "Hours"
 msgid "Hours from now"
 msgstr ""
 
-#: src/components/chat/ChatHistoryMessage.tsx:185
+#: src/components/chat/ChatHistoryMessage.tsx:205
 msgid "How Ask works and what it can do."
 msgstr ""
 
@@ -6742,7 +6742,7 @@ msgstr ""
 msgid "Open all"
 msgstr "Open all"
 
-#: src/components/chat/ChatHistoryMessage.tsx:184
+#: src/components/chat/ChatHistoryMessage.tsx:204
 msgid "Open chat documentation"
 msgstr ""
 
@@ -6752,7 +6752,7 @@ msgstr ""
 msgid "Open conversation"
 msgstr "Open conversation"
 
-#: src/components/chat/ChatHistoryMessage.tsx:178
+#: src/components/chat/ChatHistoryMessage.tsx:198
 msgid "Open documentation"
 msgstr ""
 
@@ -6798,8 +6798,8 @@ msgstr ""
 msgid "Open to the workspace"
 msgstr "Open to the workspace"
 
-#: src/components/chat/ChatHistoryMessage.tsx:227
-#: src/components/chat/ChatHistoryMessage.tsx:231
+#: src/components/chat/ChatHistoryMessage.tsx:280
+#: src/components/chat/ChatHistoryMessage.tsx:284
 msgid "Open transcript"
 msgstr ""
 
@@ -8515,7 +8515,7 @@ msgstr "Save"
 msgid "Save access"
 msgstr ""
 
-#: src/components/chat/ChatHistoryMessage.tsx:296
+#: src/components/chat/ChatHistoryMessage.tsx:349
 msgid "Save as template"
 msgstr "Save as template"
 
@@ -9372,6 +9372,10 @@ msgstr "Sort"
 msgid "Source {0}"
 msgstr "Source {0}"
 
+#: src/components/chat/ChatHistoryMessage.tsx:389
+msgid "Sources"
+msgstr ""
+
 #: src/components/project/ProjectPortalEditor.tsx:644
 msgid "Spanish"
 msgstr "Spanish"
@@ -9866,7 +9870,7 @@ msgstr ""
 msgid "The organisation this invite was for has been deleted. There's nothing to join."
 msgstr "The organisation this invite was for has been deleted. There's nothing to join."
 
-#: src/components/chat/ChatHistoryMessage.tsx:179
+#: src/components/chat/ChatHistoryMessage.tsx:199
 msgid "The page this answer refers to."
 msgstr ""
 

echo/frontend/src/locales/cs-CZ.ts

@@ -2529,7 +2529,7 @@ msgstr "Inhalt"
 msgid "Context"
 msgstr "Kontext"
 
-#: src/components/chat/ChatHistoryMessage.tsx:394
+#: src/components/chat/ChatHistoryMessage.tsx:449
 msgid "Context added:"
 msgstr "Kontext hinzugefügt:"
 
@@ -3436,7 +3436,7 @@ msgstr "Möchten Sie auf dem Laufenden bleiben?"
 
 #: src/features/sidebar/views/HelpView.tsx:36
 #: src/features/sidebar/blocks/HelpBlock.tsx:46
-#: src/components/chat/ChatHistoryMessage.tsx:172
+#: src/components/chat/ChatHistoryMessage.tsx:192
 msgid "Documentation"
 msgstr "Dokumentation"
 
@@ -4764,7 +4764,7 @@ msgstr ""
 msgid "Hours from now"
 msgstr ""
 
-#: src/components/chat/ChatHistoryMessage.tsx:185
+#: src/components/chat/ChatHistoryMessage.tsx:205
 msgid "How Ask works and what it can do."
 msgstr ""
 
@@ -6743,7 +6743,7 @@ msgstr ""
 msgid "Open all"
 msgstr ""
 
-#: src/components/chat/ChatHistoryMessage.tsx:184
+#: src/components/chat/ChatHistoryMessage.tsx:204
 msgid "Open chat documentation"
 msgstr ""
 
@@ -6753,7 +6753,7 @@ msgstr ""
 msgid "Open conversation"
 msgstr ""
 
-#: src/components/chat/ChatHistoryMessage.tsx:178
+#: src/components/chat/ChatHistoryMessage.tsx:198
 msgid "Open documentation"
 msgstr ""
 
@@ -6799,8 +6799,8 @@ msgstr ""
 msgid "Open to the workspace"
 msgstr ""
 
-#: src/components/chat/ChatHistoryMessage.tsx:227
-#: src/components/chat/ChatHistoryMessage.tsx:231
+#: src/components/chat/ChatHistoryMessage.tsx:280
+#: src/components/chat/ChatHistoryMessage.tsx:284
 msgid "Open transcript"
 msgstr ""
 
@@ -8516,7 +8516,7 @@ msgstr "Speichern"
 msgid "Save access"
 msgstr ""
 
-#: src/components/chat/ChatHistoryMessage.tsx:296
+#: src/components/chat/ChatHistoryMessage.tsx:349
 msgid "Save as template"
 msgstr "Als Vorlage speichern"
 
@@ -9373,6 +9373,10 @@ msgstr "Sortieren"
 msgid "Source {0}"
 msgstr "Quelle {0}"
 
+#: src/components/chat/ChatHistoryMessage.tsx:389
+msgid "Sources"
+msgstr ""
+
 #: src/components/project/ProjectPortalEditor.tsx:644
 msgid "Spanish"
 msgstr "Spanisch"
@@ -9867,7 +9871,7 @@ msgstr ""
 msgid "The organisation this invite was for has been deleted. There's nothing to join."
 msgstr ""
 
-#: src/components/chat/ChatHistoryMessage.tsx:179
+#: src/components/chat/ChatHistoryMessage.tsx:199
 msgid "The page this answer refers to."
 msgstr ""