Enhance citation handling and UI components

- Updated citation handling in chat messages to include citation numbers, improving clarity and usability.
- Introduced citation chips in Markdown rendering for better visual representation of citations.
- Refactored CitationRow and TextBlock components to support new citation number functionality, ensuring consistent display across the application.
- Enhanced citation normalization and numbering logic to ensure accurate citation tracking in messages.

app/prompts.py

@@ -140,8 +140,10 @@ ANSWERING_RULES = """## Answering rules
   introduces or explains the code instead.
 - Do not put all citations only in a final "Sources" section. A short sources
   recap is okay only if the answer already has inline citations.
-- Do not cite wiki pages unless the wiki page itself is the source of the
-  claim. Prefer raw docs and course lessons.
+- Never cite `wiki/` or `generated/` KB paths: they are navigation indexes,
+  not sources, and they do not resolve to citable source cards. When a wiki
+  page led you to a claim, cite the underlying `raw/` page it references
+  (open it with `run_kb_command` if you have not already).
 - If retrieval results are weak or missing, say the topic is not well
   covered by the current knowledge base rather than guessing.
 - Synthesize retrieved material into a clear teaching explanation. Do not

frontend/app/globals.css

@@ -386,6 +386,28 @@ textarea {
   text-underline-offset: 0.14em;
 }
 
+.markdown-block a.citation-chip {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 1.05rem;
+  height: 1.05rem;
+  margin-left: 0.18rem;
+  padding: 0 0.28rem;
+  border-radius: 9999px;
+  background: var(--accent-faint);
+  color: var(--accent);
+  font-size: 10px;
+  font-weight: 650;
+  line-height: 1;
+  text-decoration: none;
+  vertical-align: 0.32em;
+}
+
+.markdown-block a.citation-chip:hover {
+  background: var(--surface-strong);
+}
+
 .markdown-block hr {
   border: 0;
   border-top: 1px solid var(--hr-color);

frontend/components/chat-message.tsx

@@ -37,6 +37,8 @@ import type {
 } from "@/lib/chat-ui";
 import {
   buildActivityItems,
+  buildCitationNumbers,
+  citationNumberFor,
   getMessageCitations,
   getOrderedMessageBlocks,
   prettifyToolName,
@@ -77,6 +79,7 @@ export function ChatMessage({
   const isAssistant = message.role === "assistant";
   const contentBlocks = getOrderedMessageBlocks(message);
   const citations = isAssistant && !isStreaming ? getMessageCitations(message) : [];
+  const citationNumbers = isAssistant ? buildCitationNumbers(message) : undefined;
   const editTextareaRef = useRef<HTMLTextAreaElement>(null);
 
   useEffect(() => {
@@ -145,10 +148,16 @@ export function ChatMessage({
                   key={block.key}
                   block={block}
                   isActive={isActive}
+                  citationNumbers={citationNumbers}
                 />
               );
             })}
-            {citations.length > 0 ? <CitationRow citations={citations} /> : null}
+            {citations.length > 0 ? (
+              <CitationRow
+                citations={citations}
+                citationNumbers={citationNumbers}
+              />
+            ) : null}
           </div>
         )}
       </article>
@@ -280,14 +289,16 @@ function MessageActionButton({
 function ContentBlock({
   block,
   isActive = false,
+  citationNumbers,
 }: {
   block: TutorMessageBlock;
   isActive?: boolean;
+  citationNumbers?: Map<string, number>;
 }) {
   if (block.kind === "activity") {
     return <ActivityPanel parts={block.parts} isActive={isActive} />;
   }
-  return <TextBlock parts={block.parts} />;
+  return <TextBlock parts={block.parts} citationNumbers={citationNumbers} />;
 }
 
 function ActivityPanel({
@@ -601,13 +612,20 @@ function formatToolResultSummary({
   return "";
 }
 
-function TextBlock({ parts }: { parts: TutorMessagePart[] }) {
+function TextBlock({
+  parts,
+  citationNumbers,
+}: {
+  parts: TutorMessagePart[];
+  citationNumbers?: Map<string, number>;
+}) {
   return (
     <div className="space-y-3 text-[15px] leading-[1.72] tracking-[-0.012em] text-[var(--ink)]">
       {parts.map((part, index) => (
         <MarkdownBlock
           key={`text-${index}`}
           className="text-[15px] leading-[1.72] tracking-[-0.012em] text-[var(--ink)]"
+          citationNumbers={citationNumbers}
         >
           {part.text ?? ""}
         </MarkdownBlock>
@@ -651,7 +669,13 @@ const CITATION_KIND_META: Record<
   doc: { icon: BookOpen, label: "Docs" },
 };
 
-function CitationRow({ citations }: { citations: MessageCitation[] }) {
+function CitationRow({
+  citations,
+  citationNumbers,
+}: {
+  citations: MessageCitation[];
+  citationNumbers?: Map<string, number>;
+}) {
   return (
     <section className="mt-2 space-y-2 border-t border-[var(--line)] pt-3">
       <div className="inline-flex items-center gap-1.5 text-[10px] font-semibold uppercase tracking-[0.12em] text-[var(--muted)]">
@@ -665,6 +689,7 @@ function CitationRow({ citations }: { citations: MessageCitation[] }) {
         {citations.map((citation, index) => {
           const meta = CITATION_KIND_META[citation.kind];
           const Icon = meta.icon;
+          const number = citationNumberFor(citationNumbers, citation.url);
           return (
             <a
               key={`${citation.kind}-${citation.url}-${index}`}
@@ -674,6 +699,11 @@ function CitationRow({ citations }: { citations: MessageCitation[] }) {
               title={`${meta.label}${citation.sublabel ? ` · ${citation.sublabel}` : ""}`}
               className="group inline-flex max-w-full items-center gap-1.5 rounded-full border border-[var(--line-strong)] bg-[var(--accent-faint)] px-2.5 py-1.5 text-xs font-medium text-[var(--accent)] transition hover:border-[var(--accent)] hover:bg-[var(--surface-strong)]"
             >
+              {number !== undefined ? (
+                <span className="shrink-0 rounded-full bg-[var(--surface)] px-1.5 text-[10px] font-semibold text-[var(--accent)]">
+                  {number}
+                </span>
+              ) : null}
               <Icon className="h-3.5 w-3.5 shrink-0" />
               <span className="truncate">{citation.label}</span>
               <ExternalLink className="h-3 w-3 shrink-0 opacity-60 transition group-hover:opacity-100" />

frontend/components/markdown-block.tsx

@@ -1,15 +1,38 @@
+import type { ReactNode } from "react";
 import ReactMarkdown from "react-markdown";
 import rehypeHighlight from "rehype-highlight";
 import remarkGfm from "remark-gfm";
+import { citationNumberFor } from "@/lib/chat-ui";
 
 type MarkdownBlockProps = {
   children: string;
   className?: string;
+  citationNumbers?: Map<string, number>;
 };
 
+// Above this length the link text is a claim the model wrapped in a link, not
+// a source title; keep the text as prose and append the chip after it.
+const CITATION_TEXT_KEEP_THRESHOLD = 48;
+
+function nodeToText(node: ReactNode): string {
+  if (typeof node === "string" || typeof node === "number") {
+    return String(node);
+  }
+  if (Array.isArray(node)) {
+    return node.map(nodeToText).join("");
+  }
+  if (node && typeof node === "object" && "props" in node) {
+    return nodeToText(
+      (node as { props: { children?: ReactNode } }).props.children,
+    );
+  }
+  return "";
+}
+
 export function MarkdownBlock({
   children,
   className = "",
+  citationNumbers,
 }: MarkdownBlockProps) {
   return (
     <div className={`markdown-block ${className}`.trim()}>
@@ -17,13 +40,32 @@ export function MarkdownBlock({
         remarkPlugins={[remarkGfm]}
         rehypePlugins={[[rehypeHighlight, { detect: true, ignoreMissing: true }]]}
         components={{
-          a: ({ ...props }) => (
-            <a
-              {...props}
-              target="_blank"
-              rel="noreferrer"
-            />
-          ),
+          a: ({ children: linkChildren, href, ...props }) => {
+            const number = citationNumberFor(citationNumbers, href);
+            if (number !== undefined) {
+              const label = nodeToText(linkChildren).trim();
+              const keepText = label.length > CITATION_TEXT_KEEP_THRESHOLD;
+              return (
+                <>
+                  {keepText ? <span>{label}</span> : null}
+                  <a
+                    href={href}
+                    target="_blank"
+                    rel="noreferrer"
+                    title={label}
+                    className="citation-chip"
+                  >
+                    {number}
+                  </a>
+                </>
+              );
+            }
+            return (
+              <a {...props} href={href} target="_blank" rel="noreferrer">
+                {linkChildren}
+              </a>
+            );
+          },
         }}
       >
         {children}

frontend/lib/chat-ui.ts

@@ -180,6 +180,47 @@ export function getMessageCitations(message: TutorMessage): MessageCitation[] {
   return citations;
 }
 
+const MARKDOWN_LINK_PATTERN = /(!?)\[([^\]]*)\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g;
+
+function normalizeCitationUrl(url: string) {
+  // Mirror the server's normalize_url so inline links and data-source parts
+  // resolve to the same key.
+  return url.replace(/#.*$/, "").replace(/\/+$/, "");
+}
+
+// Number the citation links in a message's answer text by order of first
+// appearance, deduped by normalized URL. The same map drives the inline
+// citation chips and the numbers on the sources row.
+export function buildCitationNumbers(message: TutorMessage): Map<string, number> {
+  const numbers = new Map<string, number>();
+  for (const part of message.parts) {
+    if (!("type" in part) || part.type !== "text") {
+      continue;
+    }
+    const text = (part as TutorMessagePart).text ?? "";
+    for (const match of text.matchAll(MARKDOWN_LINK_PATTERN)) {
+      if (match[1] === "!") {
+        continue;
+      }
+      const key = normalizeCitationUrl(match[3] ?? "");
+      if (key && !numbers.has(key)) {
+        numbers.set(key, numbers.size + 1);
+      }
+    }
+  }
+  return numbers;
+}
+
+export function citationNumberFor(
+  numbers: Map<string, number> | undefined,
+  url: string | undefined,
+) {
+  if (!numbers || !url) {
+    return undefined;
+  }
+  return numbers.get(normalizeCitationUrl(url));
+}
+
 function cleanTitle(raw: string | undefined) {
   const trimmed = raw?.trim();
   if (!trimmed) {