improve: tour quality + layout from Claude Code source study

Prompt improvements (from studying Claude Code /init + MagicDocs source):

Investigation phase now uses Claude Code's WHY/HOW/WHERE/WHAT framing:
- WHY: what breaks without this component
- HOW: how it connects to adjacent pipeline stages
- WHERE: entry point a reader should start from
- WHAT: non-obvious pattern (class names now allowed when they clarify design)

Synthesis phase now enforces fan-out dependency graph instead of linear chain:
- depends_on = conceptual prerequisite, NOT execution order
- Most concepts should depend on concept 0 only (fan-out, not chain)
- Added explicit wrong/right examples in the prompt
- "A chain A→B→C→D is almost always wrong. Fan-out from 0 is almost always right."

Layout fix for linear chains:
- MAX_COLS = 4: caps horizontal width regardless of dependency depth
- Concepts beyond column 4 wrap into a second band below the first
- 7-wide layout becomes 2-band (4 top + 3 bottom) — fits viewport
- BAND_GAP = 80px between bands for visual separation

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

backend/services/tour_agent.py

@@ -70,11 +70,15 @@ _MAP_SYSTEM = (
 )
 
 _INVESTIGATE_SYSTEM = (
-    "You are a senior engineer doing a deep-dive into one component of a pipeline. "
-    "You know where this component sits in the larger system. "
-    "Your job: identify the KEY non-obvious design decision in this code. "
-    "State the failure mode that would occur with the naive alternative. "
+    "You are a senior engineer doing a deep-dive into one component of a codebase. "
+    "You know exactly where this component fits in the larger system. "
+    "Your job: answer four questions about this code — "
+    "WHY does this component exist (what breaks without it?), "
+    "HOW does it connect to adjacent components, "
+    "WHERE is the entry point a reader should start, "
+    "WHAT non-obvious pattern or design decision makes this work. "
     "Every claim must be grounded in the actual code shown. "
+    "Class names, function names, and file names are ENCOURAGED when they clarify the design. "
     "Return ONLY valid JSON, no markdown, no explanation."
 )
 
@@ -82,8 +86,10 @@ _SYNTHESIZE_SYSTEM = (
     "You are a senior engineer writing the guided tour you wished existed before "
     "reading this codebase. You have already traced the full pipeline and investigated "
     "each stage. Convert your traced findings into the structured tour format. "
-    "The dependency tree must reflect conceptual prerequisites: a developer cannot "
-    "understand concept B without first understanding concept A. "
+    "DEPENDENCY RULE: depends_on means 'a developer cannot understand B without first "
+    "understanding A' — it is NOT execution order. Most concepts are parallel: they "
+    "share concept 0 as a prerequisite but are independent of each other. "
+    "A chain A→B→C→D is almost always wrong. A fan-out from concept 0 is almost always right. "
     "Return ONLY valid JSON, no markdown, no explanation."
 )
 
@@ -326,21 +332,26 @@ Full pipeline (for context):
 Code for this stage — {stage_file}:
 {code_text}
 
-What is the KEY non-obvious design decision in this stage?
+Answer four questions about this component. Every answer must be grounded in the code above.
+
+1. WHY does this component exist? What breaks or degrades without it?
+2. HOW does it connect to the rest of the pipeline? What does it receive, what does it produce?
+3. WHERE should a reader start? Name the entry-point function or class.
+4. WHAT is the non-obvious pattern? Name the technique (and the class/function that implements it if helpful).
 
 Return ONLY this JSON:
 {{
-  "name": "Technique or decision (3-5 words — never a class/file/service name)",
-  "subtitle": "One sentence: the specific problem this solves in the pipeline",
-  "insight": "2-3 sentences: the naive approach and its failure mode, what this code does instead, the non-obvious insight that makes it work",
-  "key_functions": ["actual_function_1", "actual_function_2"],
-  "naive_rejected": "One sentence: what simpler approach was NOT used and why"
+  "name": "3-5 words naming the key technique or component (class names OK if they explain the design)",
+  "subtitle": "One sentence: WHY this exists — the specific problem it solves",
+  "insight": "2-3 sentences covering HOW it works and WHAT makes it non-obvious. Include the naive alternative and its failure mode.",
+  "key_functions": ["entry_point_function", "other_actual_function"],
+  "naive_rejected": "One sentence: the simpler approach that would fail and why"
 }}
 
 Rules:
-- Name the TECHNIQUE, not the artifact (bad: 'QdrantStore', good: 'Dual-Vector Hybrid Search')
-- key_functions must be actual method names visible in the code above
-- insight must state a concrete failure mode with the naive approach
+- key_functions must be actual names visible in the code above
+- insight must name a concrete failure mode with the naive approach
+- Use actual class/function names when they clarify the design (e.g. 'QdrantStore.hybrid_search')
 """
         raw = self._gen.generate(_INVESTIGATE_SYSTEM, prompt, temperature=0.0,
                                   json_mode=True, max_tokens=800)
@@ -396,13 +407,26 @@ Per-stage findings (already investigated — use these verbatim):
 
 Convert this traced understanding into a concept tour JSON.
 
-Concept id=0 (reading_order=1, depends_on=[]) MUST be the end-to-end pipeline
-overview — what enters, what stages transform it, what the user gets out.
-All other concepts must have depends_on pointing to at least one earlier concept.
+═══ DEPENDENCY RULE (CRITICAL) ═══
+depends_on means "a developer CANNOT understand concept B without first understanding A."
+It is NOT execution order.
+
+Ask yourself for each concept: "Can someone understand this WITHOUT knowing the others?"
+- If yes → depends_on: [0]  (only the pipeline overview is a prerequisite)
+- If no  → depends_on: [id of the specific concept they must know first]
+
+WRONG (chain): 1→2→3→4→5→6→7  (almost never true)
+RIGHT (fan-out): most concepts depend on 0 only, forming a tree 1-2 levels deep
+
+For a 7-concept tour the typical structure is:
+  0: pipeline overview (no deps)
+  1,2,3,4,5: core concepts, each depends on 0 only
+  6: one concept that genuinely requires knowing concept 1 or 2 first
 
+═══ FORMAT ═══
 Return ONLY this JSON:
 {{
-  "summary": "2 sentences: (1) what the user can DO with this repo and what mechanism makes it possible — name the technique. (2) the single architectural decision that shapes everything else.",
+  "summary": "2 sentences: (1) what the user can DO with this repo, naming the key technique. (2) the single architectural decision that shapes everything else.",
   "entry_point": "{entry}",
   "concepts": [
     {{
@@ -411,19 +435,19 @@ Return ONLY this JSON:
       "subtitle": "What this pipeline does for the user",
       "file": "{entry}",
       "type": "module",
-      "description": "2-3 sentences tracing the full flow: what enters, how each stage transforms it, what the user gets. Name the key files and the architectural split that makes it work.",
-      "key_items": ["function_1", "function_2"],
+      "description": "2-3 sentences: what enters, how each stage transforms it, what the user gets. Name the key files and the split that makes it work.",
+      "key_items": ["entry_function", "other_function"],
       "depends_on": [],
       "reading_order": 1,
       "ask": "How does the full pipeline work end to end?"
     }},
     {{
       "id": 1,
-      "name": "Use the exact 'name' field from stage 1 findings above",
-      "subtitle": "Use the exact 'subtitle' field from stage 1 findings above",
+      "name": "Use the exact 'name' from stage 1 findings",
+      "subtitle": "Use the exact 'subtitle' from stage 1 findings",
       "file": "file from stage 1",
       "type": "class|function|module|algorithm",
-      "description": "Use the exact 'insight' field from stage 1 findings above",
+      "description": "Use the exact 'insight' from stage 1 findings",
       "key_items": ["use exact key_functions from findings"],
       "depends_on": [0],
       "reading_order": 2,
@@ -433,9 +457,10 @@ Return ONLY this JSON:
 }}
 
 Rules:
-- 6-8 concepts total (concept 0 = pipeline overview, concepts 1+ = one per stage insight)
-- Use the EXACT name, subtitle, insight, key_functions from the per-stage findings above
+- 6-8 concepts total (concept 0 = pipeline overview, concepts 1-N = one per stage insight)
+- Use the EXACT name, subtitle, insight, key_functions from the per-stage findings
 - All concepts except id=0 must have depends_on non-empty
+- Most concepts should have depends_on: [0] — only add deeper dependencies when genuinely required
 - reading_order: sequential integers starting at 1
 - type: exactly one of class, function, module, algorithm
 """

ui/src/components/ExploreView.jsx

@@ -93,11 +93,20 @@ function expansionOffsets(selectedId, concepts, basePositions) {
 // ── Layout: topological column assignment with overflow wrapping ───────────────
 // Returns { [conceptId]: { x, y } } in canvas coordinates.
 //
-// The LLM sometimes produces shallow dependency graphs (many nodes at depth 0),
-// which naively stacks all root concepts into one tall column. We cap each
-// column at MAX_PER_COL items and push overflow into the next available column,
-// keeping the visual width reasonable and the graph readable.
+// Two kinds of overflow:
+//
+// 1. Same-depth overflow (fan-out): many nodes at depth 1 (e.g. 5 children of
+//    the pipeline overview). MAX_PER_COL = 3 caps per column and overflows into
+//    the next column, then the next depth starts in the column after that.
+//
+// 2. Too-many-columns overflow (linear chain): a sequential A→B→C→D→E→F→G
+//    produces 7 columns — too wide for the screen. MAX_COLS = 4 caps the total
+//    horizontal width. After column 3, nodes wrap into a second visual band
+//    (row), placed below the first band. This turns a 7-wide layout into a
+//    2-band layout (cols 0-3 top, cols 4-6 bottom), which fits the viewport.
 const MAX_PER_COL = 3;
+const MAX_COLS    = 4;   // wrap into a second band after this many visual columns
+const BAND_GAP    = 80;  // extra vertical gap between bands
 
 function computeLayout(concepts) {
   if (!concepts.length) return {};
@@ -125,9 +134,6 @@ function computeLayout(concepts) {
   );
 
   // Step 3: assign visual columns, capping at MAX_PER_COL items per column.
-  // Each depth level starts in its own column. If a depth has more than MAX_PER_COL
-  // nodes, overflow spills into the next column. The following depth level then
-  // starts in the column after the last one used by the previous depth.
   const colAssign = {};
   let nextCol = 0;
 
@@ -141,26 +147,56 @@ function computeLayout(concepts) {
       colAssign[node.id] = col;
       count++;
     });
-    nextCol = col + 1;  // next depth starts after the last column used here
+    nextCol = col + 1;
+  });
+
+  // Step 4: wrap columns past MAX_COLS into bands.
+  // band = Math.floor(colIndex / MAX_COLS), wrappedCol = colIndex % MAX_COLS
+  // This maps e.g. columns [0,1,2,3,4,5,6] to band 0: [0,1,2,3], band 1: [0,1,2]
+  const bandAssign = {};
+  const wrappedColAssign = {};
+  Object.entries(colAssign).forEach(([id, col]) => {
+    bandAssign[id]      = Math.floor(col / MAX_COLS);
+    wrappedColAssign[id] = col % MAX_COLS;
   });
 
-  // Step 4: assign pixel positions — group by visual column, center each vertically
-  const visualCols = {};
+  // Step 5: assign pixel positions — group by (band, wrappedCol)
+  // Compute each band's total height first so we can stack bands vertically.
+  const bandColGroups = {};   // { band_wrappedCol: [concept, ...] }
+  const bandHeights   = {};   // { band: maxColumnHeight }
+
   concepts.forEach(c => {
-    const vc = colAssign[c.id] ?? 0;
-    if (!visualCols[vc]) visualCols[vc] = [];
-    visualCols[vc].push(c);
+    const band = bandAssign[c.id] ?? 0;
+    const wc   = wrappedColAssign[c.id] ?? 0;
+    const key  = `${band}_${wc}`;
+    if (!bandColGroups[key]) bandColGroups[key] = [];
+    bandColGroups[key].push(c);
   });
-  Object.values(visualCols).forEach(arr =>
-    arr.sort((a, b) => (a.reading_order ?? 99) - (b.reading_order ?? 99))
-  );
 
-  const maxColH = Math.max(...Object.values(visualCols).map(a => a.length)) * (CARD_H + ROW_GAP);
+  Object.entries(bandColGroups).forEach(([key, nodes]) => {
+    nodes.sort((a, b) => (a.reading_order ?? 99) - (b.reading_order ?? 99));
+    const [band] = key.split("_").map(Number);
+    const h = nodes.length * (CARD_H + ROW_GAP);
+    bandHeights[band] = Math.max(bandHeights[band] ?? 0, h);
+  });
+
+  // Cumulative Y offsets per band
+  const bandStartY = {};
+  let cumY = 48;
+  const numBands = Math.max(...Object.values(bandAssign)) + 1;
+  for (let b = 0; b < numBands; b++) {
+    bandStartY[b] = cumY;
+    cumY += (bandHeights[b] ?? 0) + BAND_GAP;
+  }
+
+  // Within each band, center columns relative to the tallest column in that band
   const positions = {};
-  Object.entries(visualCols).forEach(([vc, nodes]) => {
-    const x = Number(vc) * (CARD_W + COL_GAP) + 48;
+  Object.entries(bandColGroups).forEach(([key, nodes]) => {
+    const [band, wc] = key.split("_").map(Number);
+    const x = wc * (CARD_W + COL_GAP) + 48;
+    const maxH = bandHeights[band] ?? 0;
     const colH = nodes.length * (CARD_H + ROW_GAP) - ROW_GAP;
-    const startY = (maxColH - colH) / 2 + 48;
+    const startY = bandStartY[band] + (maxH - colH) / 2;
     nodes.forEach((node, row) => {
       positions[node.id] = { x, y: startY + row * (CARD_H + ROW_GAP) };
     });