Enhance ESLint configuration and chat components

- Updated ESLint configuration to allow unused variable patterns prefixed with "_" for better code clarity.
- Refactored ChatMessage component to integrate citation resolutions, improving citation handling in messages.
- Enhanced MarkdownBlock to resolve citation URLs dynamically, ensuring accurate linking in rendered content.
- Updated SourceSidebar to streamline source information display, removing deprecated metadata references.
- Improved API types to include short labels and descriptions for sources, enhancing data representation.

frontend/components/chat-message.tsx

@@ -38,9 +38,11 @@ import type {
 import {
   buildActivityItems,
   buildCitationNumbers,
+  buildCitationResolutions,
   citationNumberFor,
   getMessageCitations,
   getOrderedMessageBlocks,
+  isHttpUrl,
   prettifyToolName,
   toolInputSummary,
 } from "@/lib/chat-ui";
@@ -79,7 +81,12 @@ 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 citationResolutions = isAssistant
+    ? buildCitationResolutions(message)
+    : undefined;
+  const citationNumbers = isAssistant
+    ? buildCitationNumbers(message, citationResolutions)
+    : undefined;
   const editTextareaRef = useRef<HTMLTextAreaElement>(null);
 
   useEffect(() => {
@@ -149,6 +156,7 @@ export function ChatMessage({
                   block={block}
                   isActive={isActive}
                   citationNumbers={citationNumbers}
+                  citationResolutions={citationResolutions}
                 />
               );
             })}
@@ -290,15 +298,23 @@ function ContentBlock({
   block,
   isActive = false,
   citationNumbers,
+  citationResolutions,
 }: {
   block: TutorMessageBlock;
   isActive?: boolean;
   citationNumbers?: Map<string, number>;
+  citationResolutions?: Map<string, string>;
 }) {
   if (block.kind === "activity") {
     return <ActivityPanel parts={block.parts} isActive={isActive} />;
   }
-  return <TextBlock parts={block.parts} citationNumbers={citationNumbers} />;
+  return (
+    <TextBlock
+      parts={block.parts}
+      citationNumbers={citationNumbers}
+      citationResolutions={citationResolutions}
+    />
+  );
 }
 
 function ActivityPanel({
@@ -323,9 +339,11 @@ function ActivityPanel({
   );
   const sourceCount = getToolPartSourceCount(parts);
 
+  // Only a genuinely unfinished tool earns a "Running ..." header; when all
+  // calls have returned (e.g. the model is reasoning after its last tool),
+  // fall through to the generic activity summary.
   const liveTool = isActive
     ? toolItems.find((item) => item.part.state !== "output-available")
-      ?? toolItems[toolItems.length - 1]
     : undefined;
 
   const summary = buildActivitySummary({
@@ -615,9 +633,11 @@ function formatToolResultSummary({
 function TextBlock({
   parts,
   citationNumbers,
+  citationResolutions,
 }: {
   parts: TutorMessagePart[];
   citationNumbers?: Map<string, number>;
+  citationResolutions?: Map<string, string>;
 }) {
   return (
     <div className="space-y-3 text-[15px] leading-[1.72] tracking-[-0.012em] text-[var(--ink)]">
@@ -626,6 +646,7 @@ function TextBlock({
           key={`text-${index}`}
           className="text-[15px] leading-[1.72] tracking-[-0.012em] text-[var(--ink)]"
           citationNumbers={citationNumbers}
+          citationResolutions={citationResolutions}
         >
           {part.text ?? ""}
         </MarkdownBlock>
@@ -690,15 +711,12 @@ function CitationRow({
           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}`}
-              href={citation.url}
-              target="_blank"
-              rel="noreferrer"
-              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)]"
-            >
+          // Server-resolved URLs are trusted data but external input
+          // (corpus frontmatter, web results, manifest path fallbacks);
+          // only http(s) gets a navigable anchor.
+          const navigable = isHttpUrl(citation.url);
+          const cardChildren = (
+            <>
               {number !== undefined ? (
                 <span className="shrink-0 rounded-full bg-[var(--surface)] px-1.5 text-[10px] font-semibold text-[var(--accent)]">
                   {number}
@@ -706,7 +724,32 @@ function CitationRow({
               ) : 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" />
+              {navigable ? (
+                <ExternalLink className="h-3 w-3 shrink-0 opacity-60 transition group-hover:opacity-100" />
+              ) : null}
+            </>
+          );
+          const cardKey = `${citation.kind}-${citation.url}-${index}`;
+          const cardTitle = `${meta.label}${citation.sublabel ? ` · ${citation.sublabel}` : ""}`;
+          const cardClassName =
+            "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)]";
+          if (!navigable) {
+            return (
+              <span key={cardKey} title={cardTitle} className={cardClassName}>
+                {cardChildren}
+              </span>
+            );
+          }
+          return (
+            <a
+              key={cardKey}
+              href={citation.url}
+              target="_blank"
+              rel="noreferrer"
+              title={cardTitle}
+              className={cardClassName}
+            >
+              {cardChildren}
             </a>
           );
         })}

frontend/components/chat-shell.tsx

@@ -9,7 +9,6 @@ import {
   useLayoutEffect,
   useRef,
   useState,
-  useTransition,
 } from "react";
 import { ChatMessage } from "@/components/chat-message";
 import { SourceSidebar } from "@/components/source-sidebar";
@@ -76,7 +75,6 @@ export function ChatShell() {
   const [copiedMessageId, setCopiedMessageId] = useState<string | null>(null);
   const [editingMessageId, setEditingMessageId] = useState<string | null>(null);
   const [editingText, setEditingText] = useState("");
-  const [, startTransition] = useTransition();
   const threadViewportRef = useRef<HTMLDivElement>(null);
   const composerInputRef = useRef<HTMLTextAreaElement>(null);
   const pendingScrollRef = useRef(false);
@@ -97,7 +95,10 @@ export function ChatShell() {
       if (part.type === "data-thread") {
         const nextThreadId = (part as ThreadDataPart).data.threadId;
         if (nextThreadId) {
-          startTransition(() => setThreadId(nextThreadId));
+          // Urgent update on purpose: deferring it (startTransition) lets a
+          // concurrent "New chat" reset finish first and then be overwritten
+          // by the stale thread id.
+          setThreadId(nextThreadId);
         }
       }
     },
@@ -190,7 +191,10 @@ export function ChatShell() {
   }, [selectedModel]);
 
   const isStreaming = status === "submitted" || status === "streaming";
-  const isReady = status === "ready";
+  // After a stream error the SDK parks status on "error" until clearError()
+  // or the next request; handleSubmit clears it, so the error state must
+  // stay sendable or the Send button locks out mouse users for good.
+  const canSend = status === "ready" || status === "error";
   const typedMessages = messages as TutorMessage[];
   const latestMessage = typedMessages[typedMessages.length - 1];
   const streamingAssistantId =
@@ -495,7 +499,7 @@ export function ChatShell() {
                     selectedModel={selectedModel}
                   />
                   <ComposerActionButton
-                    disabled={!isStreaming && (!input.trim() || !isReady)}
+                    disabled={!isStreaming && (!input.trim() || !canSend)}
                     isStreaming={isStreaming}
                     streamingLabel={streamingWord}
                     onClick={

frontend/components/markdown-block.tsx

@@ -1,13 +1,18 @@
 import type { ReactNode } from "react";
-import ReactMarkdown from "react-markdown";
+import ReactMarkdown, { defaultUrlTransform } from "react-markdown";
 import rehypeHighlight from "rehype-highlight";
 import remarkGfm from "remark-gfm";
-import { citationNumberFor } from "@/lib/chat-ui";
+import {
+  citationNumberFor,
+  isHttpUrl,
+  resolveCitationHref,
+} from "@/lib/chat-ui";
 
 type MarkdownBlockProps = {
   children: string;
   className?: string;
   citationNumbers?: Map<string, number>;
+  citationResolutions?: Map<string, string>;
 };
 
 // Above this length the link text is a claim the model wrapped in a link, not
@@ -33,14 +38,21 @@ export function MarkdownBlock({
   children,
   className = "",
   citationNumbers,
+  citationResolutions,
 }: MarkdownBlockProps) {
   return (
     <div className={`markdown-block ${className}`.trim()}>
       <ReactMarkdown
         remarkPlugins={[remarkGfm]}
         rehypePlugins={[[rehypeHighlight, { detect: true, ignoreMissing: true }]]}
+        // KB references (kb://doc/<id>, raw/... paths) must resolve before the
+        // default transform runs: it blanks the kb:// scheme and would leave
+        // raw paths as relative hrefs into the app's own origin.
+        urlTransform={(url) =>
+          resolveCitationHref(url, citationResolutions) ?? defaultUrlTransform(url)
+        }
         components={{
-          a: ({ children: linkChildren, href, ...props }) => {
+          a: ({ children: linkChildren, href, node: _node, ...props }) => {
             const number = citationNumberFor(citationNumbers, href);
             if (number !== undefined) {
               const label = nodeToText(linkChildren).trim();
@@ -60,6 +72,12 @@ export function MarkdownBlock({
                 </>
               );
             }
+            // An unresolved KB reference arrives here with an empty (kb://
+            // blanked by the transform) or relative (raw/...) href; a real
+            // anchor would open the app's own origin in a new tab.
+            if (!isHttpUrl(href) && !href?.startsWith("mailto:")) {
+              return <span>{linkChildren}</span>;
+            }
             return (
               <a {...props} href={href} target="_blank" rel="noreferrer">
                 {linkChildren}

frontend/components/source-sidebar.tsx

@@ -23,8 +23,6 @@ import {
 } from "react";
 import { createPortal } from "react-dom";
 import type { TutorSource, TutorTool } from "@/lib/api";
-import { COURSE_METADATA } from "@/lib/course-metadata";
-import { DOC_METADATA } from "@/lib/doc-metadata";
 
 type SourceSidebarProps = {
   onNewChat: () => void;
@@ -486,23 +484,22 @@ function formatIndexedMonth(isoDate: string | null | undefined): string | null {
 }
 
 function getPopoverInfo(source: TutorSource): PopoverInfo | undefined {
+  // Description and link come from the registry via /api/tools; the frontend
+  // renders them verbatim so adding a source needs no UI edit.
+  if (!source.description || !source.infoUrl) return undefined;
   if (source.group === "courses") {
-    const meta = COURSE_METADATA[source.key];
-    if (!meta) return undefined;
     return {
-      description: meta.description,
-      linkUrl: meta.academyUrl,
+      description: source.description,
+      linkUrl: source.infoUrl,
       linkLabel: "View on Academy",
     };
   }
-  const meta = DOC_METADATA[source.key];
-  if (!meta) return undefined;
   const indexedMonth = formatIndexedMonth(source.indexedAt);
   const metaParts = [source.version, indexedMonth ? `indexed ${indexedMonth}` : null]
     .filter((part): part is string => Boolean(part));
   return {
-    description: meta.description,
-    linkUrl: meta.docsUrl,
+    description: source.description,
+    linkUrl: source.infoUrl,
     linkLabel: "View docs",
     meta: metaParts.length > 0 ? metaParts.join(" · ") : undefined,
   };
@@ -565,9 +562,11 @@ function SourceRow({
         <button
           type="button"
           onClick={() => onToggle(source.key)}
+          aria-pressed={selected}
           className="flex min-w-0 flex-1 items-center gap-2 text-left"
         >
           <span
+            aria-hidden="true"
             className={clsx(
               "flex h-4 w-4 shrink-0 items-center justify-center rounded-full border text-[9px] font-bold",
               selected
@@ -580,7 +579,7 @@ function SourceRow({
             ✓
           </span>
           <span className="min-w-0 truncate text-[12.5px] font-medium tracking-[-0.01em]">
-            {formatSourceLabel(source.label)}
+            {source.shortLabel || source.label}
           </span>
         </button>
         {popover ? (
@@ -781,7 +780,3 @@ function ToggleToolRow({
     </div>
   );
 }
-
-function formatSourceLabel(label: string) {
-  return label.replace(/\s+Docs$/, "");
-}

frontend/eslint.config.mjs

@@ -1,6 +1,23 @@
 import nextVitals from "eslint-config-next/core-web-vitals";
 import nextTypescript from "eslint-config-next/typescript";
 
-const eslintConfig = [...nextVitals, ...nextTypescript];
+const eslintConfig = [
+  ...nextVitals,
+  ...nextTypescript,
+  {
+    rules: {
+      // Allow the standard "intentionally unused" idioms: _-prefixed
+      // bindings and siblings dropped via rest destructuring.
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+          ignoreRestSiblings: true,
+        },
+      ],
+    },
+  },
+];
 
 export default eslintConfig;

frontend/lib/api.ts

@@ -1,6 +1,9 @@
 export type TutorSource = {
   key: string;
   label: string;
+  shortLabel: string;
+  description?: string | null;
+  infoUrl?: string | null;
   group: "courses" | "docs";
   selectedByDefault: boolean;
   version?: string | null;
@@ -43,6 +46,8 @@ export type SourcePartData = {
   sourceLabel: string;
   score: number;
   group: string;
+  // KB-root-relative file path ("raw/docs/...") when the source is a KB file.
+  path?: string;
 };
 
 const FALLBACK_API_BASE_URL = "http://127.0.0.1:8000";

frontend/lib/chat-ui.ts

@@ -180,29 +180,159 @@ 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(/\/+$/, "");
+  // Mirror the server's normalize_url (drop fragment and trailing slash),
+  // then canonicalize percent-encoding: react-markdown renders hrefs through
+  // micromark's normalizeUri, so the rendered href may be an encoded variant
+  // of the raw answer text. Decode-then-encode maps both to one form (it is
+  // idempotent across that encoding); URLs that fail to decode stay as-is.
+  const base = url.replace(/#.*$/, "").replace(/\/+$/, "");
+  try {
+    return encodeURI(decodeURI(base));
+  } catch {
+    return base;
+  }
+}
+
+// Drop fenced code blocks and inline code spans before scanning for links:
+// rendered code never produces anchors, so a markdown link inside code must
+// not consume a citation number. The $ alternates keep a streaming,
+// not-yet-closed fence from leaking back in.
+function stripCodeSegments(text: string) {
+  return text
+    .replace(/```[\s\S]*?(?:```|$)/g, " ")
+    .replace(/~~~[\s\S]*?(?:~~~|$)/g, " ")
+    .replace(/`[^`\n]*`/g, " ");
+}
+
+// micromark parses balanced parens inside a link destination, so a regex that
+// stops at the first ")" truncates URLs like .../Spring_(framework). Scan the
+// destination the way the parser does: <...> form, or up to whitespace / the
+// first unbalanced closing paren.
+function scanLinkDestination(text: string, start: number): string {
+  let index = start;
+  while (index < text.length && /\s/.test(text[index])) {
+    index += 1;
+  }
+  if (text[index] === "<") {
+    const end = text.indexOf(">", index + 1);
+    return end === -1 ? "" : text.slice(index + 1, end);
+  }
+  let depth = 0;
+  let end = index;
+  while (end < text.length) {
+    const char = text[end];
+    if (/\s/.test(char)) {
+      break;
+    }
+    if (char === "(") {
+      depth += 1;
+    } else if (char === ")") {
+      if (depth === 0) {
+        break;
+      }
+      depth -= 1;
+    }
+    end += 1;
+  }
+  return text.slice(index, end);
+}
+
+const LINK_OPENER_PATTERN = /(!?)\[[^\]]*\]\(/g;
+
+function extractMarkdownLinkUrls(text: string): string[] {
+  const urls: string[] = [];
+  const scannable = stripCodeSegments(text);
+  for (const match of scannable.matchAll(LINK_OPENER_PATTERN)) {
+    if (match[1] === "!") {
+      continue;
+    }
+    const url = scanLinkDestination(scannable, match.index + match[0].length);
+    if (url) {
+      urls.push(url);
+    }
+  }
+  return urls;
+}
+
+export function isHttpUrl(url: string | undefined): boolean {
+  return Boolean(url && /^https?:\/\//i.test(url.trim()));
+}
+
+// The system prompt lets the model cite KB-browsed files as kb://doc/<id> or
+// KB-root paths like raw/docs/peft/lora.md; normalize the path variants the
+// model may produce to the KB-root-relative form the server sends.
+function normalizeKbPath(ref: string) {
+  let value = ref.trim();
+  if (value.startsWith("./")) {
+    value = value.slice(2);
+  }
+  if (value.startsWith("data/kb/")) {
+    value = value.slice("data/kb/".length);
+  }
+  return value;
+}
+
+// Map inline KB references (kb://doc/<id>, raw/... paths) to the resolved
+// https URL of the matching data-source part, so inline citations of
+// KB-browsed files link to the real page instead of rendering as a dead
+// kb:// or relative href.
+export function buildCitationResolutions(
+  message: TutorMessage,
+): Map<string, string> {
+  const resolutions = new Map<string, string>();
+  for (const part of message.parts) {
+    if (!("type" in part) || part.type !== "data-source") {
+      continue;
+    }
+    const data = (part as TutorMessagePart).data as SourcePartData | undefined;
+    const url = data?.url?.trim();
+    if (!data || !isHttpUrl(url)) {
+      continue;
+    }
+    if (data.docId) {
+      resolutions.set(`kb://doc/${data.docId}`, url as string);
+    }
+    const path = normalizeKbPath(data.path ?? "");
+    if (path) {
+      resolutions.set(path, url as string);
+    }
+  }
+  return resolutions;
+}
+
+export function resolveCitationHref(
+  href: string | undefined,
+  resolutions: Map<string, string> | undefined,
+): string | undefined {
+  if (!href || !resolutions || resolutions.size === 0) {
+    return undefined;
+  }
+  return resolutions.get(href.trim()) ?? resolutions.get(normalizeKbPath(href));
 }
 
 // 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> {
+// appearance, deduped by normalized URL. KB references are keyed under their
+// resolved https URL so the inline chip and the source card share a number;
+// references that resolve to nothing navigable get no number (the renderer
+// shows them as plain text instead of a broken chip). The same map drives the
+// inline citation chips and the numbers on the sources row.
+export function buildCitationNumbers(
+  message: TutorMessage,
+  resolutions?: Map<string, string>,
+): 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] === "!") {
+    for (const url of extractMarkdownLinkUrls(text)) {
+      const resolved = resolveCitationHref(url, resolutions) ?? url;
+      if (!isHttpUrl(resolved)) {
         continue;
       }
-      const key = normalizeCitationUrl(match[3] ?? "");
+      const key = normalizeCitationUrl(resolved);
       if (key && !numbers.has(key)) {
         numbers.set(key, numbers.size + 1);
       }

frontend/lib/course-metadata.ts

@@ -1,29 +0,0 @@
-export type CourseMetadata = {
-  description: string;
-  academyUrl: string;
-};
-
-export const COURSE_METADATA: Record<string, CourseMetadata> = {
-  full_stack_ai_engineering: {
-    description:
-      "Full-stack LLM engineering, covering RAG, fine-tuning, evaluation, and deploying production systems end-to-end. The deepest technical course.",
-    academyUrl:
-      "https://academy.towardsai.net/courses/beginner-to-advanced-llm-dev",
-  },
-  beginner_python_for_ai_engineering: {
-    description:
-      "Python for the LLM era: API integration, using open-source models, and core training/testing workflows. Assumes no prior Python.",
-    academyUrl: "https://academy.towardsai.net/courses/python-for-genai",
-  },
-  master_ai_for_work: {
-    description:
-      "Non-engineer course on using AI tools (ChatGPT, Claude, etc.) for workplace productivity and rolling them out across a team.",
-    academyUrl:
-      "https://academy.towardsai.net/courses/ai-business-professionals",
-  },
-  agentic_ai_engineering: {
-    description:
-      "Designing, building, evaluating, and deploying production-grade AI agents end-to-end.",
-    academyUrl: "https://academy.towardsai.net/courses/agent-engineering",
-  },
-};

frontend/lib/doc-metadata.ts

@@ -1,57 +0,0 @@
-export type DocMetadata = {
-  description: string;
-  docsUrl: string;
-};
-
-export const DOC_METADATA: Record<string, DocMetadata> = {
-  transformers: {
-    description:
-      "Hugging Face library for state-of-the-art NLP and multimodal models. Load, run, and train pretrained transformers.",
-    docsUrl: "https://huggingface.co/docs/transformers",
-  },
-  peft: {
-    description:
-      "Parameter-Efficient Fine-Tuning: LoRA, prefix tuning, and other methods for adapting large models with minimal compute.",
-    docsUrl: "https://huggingface.co/docs/peft",
-  },
-  trl: {
-    description:
-      "Train language models with reinforcement learning. Covers SFT, DPO, PPO, and other alignment techniques.",
-    docsUrl: "https://huggingface.co/docs/trl",
-  },
-  llama_index: {
-    description:
-      "Framework for building RAG apps: ingestion, indexing, retrievers, and query engines over your own data.",
-    docsUrl: "https://docs.llamaindex.ai",
-  },
-  langchain: {
-    description:
-      "Framework for building LLM apps: chains, agents, tool-calling, and production observability.",
-    docsUrl: "https://docs.langchain.com/oss/python/langchain/overview",
-  },
-  langgraph: {
-    description:
-      "Graph-based runtime for reliable, stateful AI agents with persistence, streaming, human review, and deployment patterns.",
-    docsUrl: "https://docs.langchain.com/oss/python/langgraph/overview",
-  },
-  deep_agents: {
-    description:
-      "LangChain's deep agent harness for planning, delegation, filesystem context, and longer-running agent workflows.",
-    docsUrl: "https://docs.langchain.com/oss/python/deepagents/overview",
-  },
-  openai_cookbooks: {
-    description:
-      "Example notebooks and recipes from OpenAI covering practical patterns for using their APIs.",
-    docsUrl: "https://cookbook.openai.com",
-  },
-  openai_docs: {
-    description:
-      "Official OpenAI API, Agents SDK, and Codex documentation from the developer docs Markdown index.",
-    docsUrl: "https://developers.openai.com",
-  },
-  claude_code_docs: {
-    description:
-      "Official Claude Code and Claude Agent SDK documentation from Anthropic's Markdown index.",
-    docsUrl: "https://code.claude.com/docs/en/overview",
-  },
-};