tour-builder agent during the /understand analysis. They give you a structured path through the architecture — ordered by dependency so you understand foundations before details.
Tours are accessible from two places:
- The Start Guided Tour button in the ProjectOverview sidebar panel (visible in all personas)
- The LearnPanel in the sidebar when the Learn persona is active
Tour structure
A tour is a list of steps stored in the knowledge graph under thetour field. Steps are sorted by their order value before display.
Each step contains:
| Field | Description |
|---|---|
order | Integer defining the step’s position in the sequence |
title | Short heading for the step |
description | Markdown-formatted explanation of the concepts covered |
nodeIds | Array of node IDs to highlight in the graph for this step |
languageLesson | Optional plain-text explanation of a programming pattern used in the step’s nodes |
How tours are generated
Thetour-builder agent (powered by Claude Opus for quality) runs after the architecture-analyzer completes. It uses a heuristic ordering strategy:
- Start with high-level entry points (main files, root modules, public API surfaces)
- Follow dependency edges to traverse the graph in topological order
- Group related nodes into thematic steps
- Add language lesson context where notable patterns are detected
Tours are regenerated each time you run
/understand. If you add significant new code, re-run the analysis to get updated tour steps that cover the new functionality.Navigating a tour
Start the tour
Click Start Tour in the LearnPanel (Learn persona) or Start Guided Tour in the ProjectOverview sidebar. The first step loads immediately.
Read the step content
The LearnPanel shows the step title, a markdown description, an optional language lesson callout, and pills for each referenced component.
Inspect highlighted nodes
The graph automatically pans and zooms to fit the nodes referenced by the current step. Highlighted nodes have a pulsing gold ring (
animate-gold-pulse).Click referenced components
Click any Referenced Components pill to select that node and open its details in the CodeViewer overlay. The tour stays active.
Move between steps
Use Prev and Next buttons at the bottom of the panel, or click any dot in the step indicator to jump directly to that step.
Progress indicator
The LearnPanel header shows the current step number and total (e.g.,3 / 8). A gold progress bar below the header fills proportionally as you advance.
Below the navigation buttons, step dots let you jump to any step directly:
- Gold dot — current step
- Dark dot — other steps (click to jump)
Language lessons
Each step can include a Language Lesson — a plain-text explanation of a programming pattern found in the step’s nodes. These appear in a gold-tinted callout box within the step. Thetour-builder agent recognizes 12 programming patterns and annotates them in context:
| Pattern | Description |
|---|---|
| Generics | Type-parameterized functions and classes |
| Closures | Functions that capture variables from their enclosing scope |
| Decorators | Annotations that wrap or modify class and function behavior |
| Promises | Asynchronous operations and promise chaining |
| Iterators | Objects that implement the iterator protocol |
| Generators | Functions that yield values lazily |
| Higher-order functions | Functions that take or return other functions |
| Dependency injection | Passing dependencies as arguments rather than importing them directly |
| Observer pattern | Event emitters and subscriber callbacks |
| Factory pattern | Functions or classes that create other objects |
| Memoization | Caching function results to avoid redundant computation |
| Recursion | Functions that call themselves to solve sub-problems |
Using tours to onboard
Guided tours are most valuable when you are joining a new project or reviewing an unfamiliar codebase before a code review. A typical onboarding workflow:- Run
/understandon the repository - Open the dashboard with
/understand-dashboard - The Learn persona is active by default — click Start Tour
- Work through every step before opening any source files
- After the tour, use search and node selection to drill into areas of interest
- Run
/understand-diffbefore reviewing a pull request to see which tour steps are affected by the changes
If no tour is available (the
tour array in the knowledge graph is empty), the LearnPanel displays a message explaining that no tour has been generated. Re-running /understand with a complete codebase will produce a tour.