Fix duplicate graph, agent error handling, and UI clarity

Bugs fixed:
- CodeGraph: cancelled flag prevents StrictMode double-render (duplicate nodes)
- Agent stream: try/except wraps generator, yields event:error with human-readable
message instead of silently closing connection (was showing 'Error: connection lost')
- api.js: handles event:error from agent stream, shows real error in chat bubble

UI clarity:
- Empty state when no repos: 3-step onboarding (Index → Ask → Agent/Graph)
- Empty state when repos exist: suggestion buttons pre-fill the textarea
- Agent mode hint shown below suggestions when agent mode is on
- Input bar shows mode badge '✦ Agent — searches multiple times, shows reasoning'
- Ask button says 'Run Agent' in agent mode
- Graph hint link from suggest state

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/main.py

@@ -457,25 +457,36 @@ async def agent_stream(
     import json
 
     def event_stream():
-        for event in agent_svc.stream(question, repo_filter=repo):
-            etype = event["type"]
-
-            if etype == "tool_call":
-                payload = json.dumps({"tool": event["tool"], "input": event["input"]})
-                yield f"event: tool_call\ndata: {payload}\n\n"
-
-            elif etype == "tool_result":
-                payload = json.dumps({"tool": event["tool"], "output": event["output"]})
-                yield f"event: tool_result\ndata: {payload}\n\n"
-
-            elif etype == "token":
-                safe = event["text"].replace("\n", "\\n")
-                yield f"data: {safe}\n\n"
-
-            elif etype == "done":
-                payload = json.dumps({"iterations": event["iterations"]})
-                yield f"event: done\ndata: {payload}\n\n"
-                yield "data: [DONE]\n\n"
+        try:
+            for event in agent_svc.stream(question, repo_filter=repo):
+                etype = event["type"]
+
+                if etype == "tool_call":
+                    payload = json.dumps({"tool": event["tool"], "input": event["input"]})
+                    yield f"event: tool_call\ndata: {payload}\n\n"
+
+                elif etype == "tool_result":
+                    payload = json.dumps({"tool": event["tool"], "output": event["output"]})
+                    yield f"event: tool_result\ndata: {payload}\n\n"
+
+                elif etype == "token":
+                    safe = event["text"].replace("\n", "\\n")
+                    yield f"data: {safe}\n\n"
+
+                elif etype == "done":
+                    payload = json.dumps({"iterations": event["iterations"]})
+                    yield f"event: done\ndata: {payload}\n\n"
+                    yield "data: [DONE]\n\n"
+        except Exception as e:
+            # Surface the real error to the frontend instead of silently closing
+            err_msg = str(e)
+            if "credit" in err_msg.lower() or "billing" in err_msg.lower():
+                err_msg = "Anthropic API credits exhausted. Add credits at console.anthropic.com."
+            elif "api_key" in err_msg.lower():
+                err_msg = "ANTHROPIC_API_KEY not configured on this server."
+            payload = json.dumps({"message": err_msg})
+            yield f"event: error\ndata: {payload}\n\n"
+            yield "data: [DONE]\n\n"
 
     return StreamingResponse(event_stream(), media_type="text/event-stream")
 

ui/src/App.jsx

@@ -239,13 +239,71 @@ export default function App() {
           <>
             {messages.length === 0 ? (
               <div className="empty-state">
-                <div className="icon">💬</div>
-                <h2>Ask about a codebase</h2>
-                <p>
-                  {repos.length === 0
-                    ? "Index a GitHub repo using the sidebar, then ask questions about it."
-                    : "Select a repo from the sidebar or ask across all indexed repos."}
-                </p>
+                {repos.length === 0 ? (
+                  // Step 1: no repos yet
+                  <>
+                    <div className="onboarding-steps">
+                      <div className="onboarding-step active">
+                        <span className="step-num">1</span>
+                        <div>
+                          <strong>Paste a GitHub URL in the sidebar</strong>
+                          <p>e.g. <code>github.com/karpathy/micrograd</code></p>
+                          <p>The app downloads and indexes every function and class.</p>
+                        </div>
+                      </div>
+                      <div className="onboarding-step">
+                        <span className="step-num">2</span>
+                        <div>
+                          <strong>Ask a question</strong>
+                          <p>e.g. <em>"How does backward() work?"</em></p>
+                          <p>The app finds the relevant code and an AI explains it with citations.</p>
+                        </div>
+                      </div>
+                      <div className="onboarding-step">
+                        <span className="step-num">3</span>
+                        <div>
+                          <strong>Try Agent mode or the Graph view</strong>
+                          <p><strong>Agent</strong> — the AI searches multiple times, shows its reasoning step by step.</p>
+                          <p><strong>Graph</strong> — a visual map of which functions call which.</p>
+                        </div>
+                      </div>
+                    </div>
+                  </>
+                ) : (
+                  // Step 2: repos indexed, suggest questions
+                  <div className="suggest-state">
+                    <h2>What do you want to know?</h2>
+                    <p>Try one of these or ask your own:</p>
+                    <div className="suggestions">
+                      {[
+                        "Give me a high-level overview of this repo",
+                        "How does the main class work?",
+                        "What does the training loop do?",
+                        "How is backpropagation implemented?",
+                        "What are the entry points to this codebase?",
+                      ].map(q => (
+                        <button
+                          key={q}
+                          className="suggestion-btn"
+                          onClick={() => { setInput(q); textareaRef.current?.focus(); }}
+                        >
+                          {q}
+                        </button>
+                      ))}
+                    </div>
+                    {agentMode && (
+                      <div className="mode-hint">
+                        <strong>Agent mode on</strong> — the AI will search the codebase multiple times
+                        and show you each step before answering. Slower but more thorough.
+                      </div>
+                    )}
+                    {activeRepo && (
+                      <button className="graph-hint-btn" onClick={() => setView("graph")}>
+                        Or view the call graph for {activeRepo} →
+                      </button>
+                    )}
+                  </div>
+                )}
               </div>
             ) : (
               <div className="messages" ref={scrollRef}>
@@ -256,22 +314,29 @@ export default function App() {
 
             {/* Input */}
             <div className="input-bar">
-              <textarea
-                ref={textareaRef}
-                rows={1}
-                placeholder={placeholder}
-                value={input}
-                onChange={(e) => setInput(e.target.value)}
-                onKeyDown={handleKeyDown}
-                disabled={streaming}
-              />
-              <button
-                className="btn"
-                onClick={handleSubmit}
-                disabled={!input.trim() || streaming}
-              >
-                {streaming ? <span className="spinner" /> : "Ask"}
-              </button>
+              {agentMode && (
+                <div className="input-mode-badge">
+                  ✦ Agent — searches multiple times, shows reasoning
+                </div>
+              )}
+              <div className="input-row">
+                <textarea
+                  ref={textareaRef}
+                  rows={1}
+                  placeholder={agentMode ? "Ask a complex question — the agent will reason step by step…" : placeholder}
+                  value={input}
+                  onChange={(e) => setInput(e.target.value)}
+                  onKeyDown={handleKeyDown}
+                  disabled={streaming}
+                />
+                <button
+                  className="btn"
+                  onClick={handleSubmit}
+                  disabled={!input.trim() || streaming}
+                >
+                  {streaming ? <span className="spinner" /> : agentMode ? "Run Agent" : "Ask"}
+                </button>
+              </div>
             </div>
           </>
         )}

ui/src/api.js

@@ -123,6 +123,16 @@ export function streamAgentQuery({ question, repo, onToolCall, onToolResult, onT
     onDone?.(iterations);
   });
 
+  // Named event: server-side error (API credits, config issues, etc.)
+  es.addEventListener("error", (e) => {
+    try {
+      const { message } = JSON.parse(e.data);
+      onError?.(message);
+    } catch {
+      onError?.("Agent error — check server logs.");
+    }
+  });
+
   // Default events: token text (or [DONE] sentinel)
   es.onmessage = (e) => {
     if (e.data === "[DONE]") {

ui/src/components/CodeGraph.jsx

@@ -89,32 +89,40 @@ export default function CodeGraph({ repo, onAskAbout }) {
   useEffect(() => {
     if (!repo || !svgRef.current) return;
 
-    // ── Fetch graph data ────────────────────────────────────────────────────
+    // cancelled flag prevents StrictMode's double-invoke from rendering twice.
+    // React StrictMode in dev runs effects twice (mount → cleanup → mount) to
+    // detect side effects. Without this flag, both fetches complete and both
+    // call _renderGraph, appending duplicate SVG elements.
+    let cancelled = false;
+
     setLoading(true);
     setError(null);
+    d3.select(svgRef.current).selectAll("*").remove();
 
     import("../api").then(({ fetchGraph }) =>
       fetchGraph(repo)
         .then(data => {
+          if (cancelled) return;
           setStats(data.stats);
           setLoading(false);
           if (data.nodes.length === 0) {
-            setError("No function/class nodes found. Re-ingest the repo to extract call data.");
+            setError("No function/class nodes found. Re-ingest the repo to get call data.");
             return;
           }
           _renderGraph(svgRef.current, data, setTooltip, onAskAbout);
         })
         .catch(err => {
+          if (cancelled) return;
           setLoading(false);
           setError(err.message);
         })
     );
 
-    // Cleanup: stop any running simulation when repo changes or component unmounts
     return () => {
-      if (svgRef.current) d3.select(svgRef.current).selectAll("*").remove();
+      cancelled = true;
+      d3.select(svgRef.current).selectAll("*").remove();
     };
-  }, [repo]);  // re-render whenever active repo changes
+  }, [repo]);
 
   return (
     <div className="graph-container">

ui/src/index.css

@@ -349,9 +349,14 @@ body {
 
 /* ── Input bar ───────────────────────────────────────────────── */
 .input-bar {
-  padding: 12px 20px;
+  padding: 10px 20px 12px;
   border-top: 1px solid var(--border);
   background: var(--surface);
+  display: flex;
+  flex-direction: column;
+}
+
+.input-row {
   display: flex;
   gap: 10px;
   align-items: flex-end;
@@ -384,15 +389,111 @@ body {
   flex-direction: column;
   align-items: center;
   justify-content: center;
-  gap: 12px;
+  padding: 40px 20px;
+  overflow-y: auto;
+}
+
+/* Onboarding: 3-step guide shown when no repos indexed yet */
+.onboarding-steps {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  max-width: 480px;
+  width: 100%;
+}
+
+.onboarding-step {
+  display: flex;
+  gap: 14px;
+  align-items: flex-start;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: 14px 16px;
+  opacity: 0.5;
+}
+.onboarding-step.active { opacity: 1; border-color: var(--accent); }
+
+.step-num {
+  background: var(--accent);
+  color: #fff;
+  border-radius: 50%;
+  width: 22px; height: 22px;
+  display: flex; align-items: center; justify-content: center;
+  font-size: 11px; font-weight: 700;
+  flex-shrink: 0;
+  margin-top: 1px;
+}
+
+.onboarding-step strong { font-size: 14px; color: var(--text); display: block; margin-bottom: 4px; }
+.onboarding-step p { font-size: 12px; color: var(--muted); margin: 2px 0; line-height: 1.5; }
+.onboarding-step code { font-family: "JetBrains Mono", monospace; color: var(--accent); font-size: 11px; }
+
+/* Suggest state: shown when repos exist but no messages yet */
+.suggest-state { max-width: 520px; width: 100%; text-align: center; }
+.suggest-state h2 { font-size: 17px; color: var(--text); margin-bottom: 6px; }
+.suggest-state > p { font-size: 13px; color: var(--muted); margin-bottom: 14px; }
+
+.suggestions {
+  display: flex;
+  flex-direction: column;
+  gap: 7px;
+  margin-bottom: 16px;
+}
+
+.suggestion-btn {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  color: var(--text);
+  cursor: pointer;
+  font-family: inherit;
+  font-size: 13px;
+  padding: 9px 14px;
+  text-align: left;
+  transition: border-color 0.15s, background 0.15s;
+}
+.suggestion-btn:hover { border-color: var(--accent); background: var(--accent-dim); }
+
+.mode-hint {
+  background: var(--accent-dim);
+  border: 1px solid var(--accent);
+  border-radius: 8px;
+  color: var(--accent);
+  font-size: 12px;
+  line-height: 1.5;
+  margin-bottom: 12px;
+  padding: 9px 14px;
+  text-align: left;
+}
+
+.graph-hint-btn {
+  background: none;
+  border: none;
   color: var(--muted);
-  text-align: center;
-  padding: 40px;
+  cursor: pointer;
+  font-family: inherit;
+  font-size: 12px;
+  padding: 4px;
+  text-decoration: underline;
+  text-decoration-style: dotted;
+}
+.graph-hint-btn:hover { color: var(--text); }
+
+/* ── Input bar ── mode badge + row layout ────────────────────── */
+.input-mode-badge {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--accent);
+  padding: 4px 0 6px;
+  letter-spacing: 0.03em;
 }
 
-.empty-state .icon { font-size: 40px; }
-.empty-state h2 { font-size: 18px; color: var(--text); }
-.empty-state p { font-size: 14px; max-width: 320px; line-height: 1.6; }
+.input-row {
+  display: flex;
+  gap: 10px;
+  align-items: flex-end;
+}
 
 /* ── Status bar ──────────────────────────────────────────────── */
 .status-bar {