# Navigation & Controls

Master Gonzo's keyboard shortcuts and mouse controls to analyze logs efficiently. This comprehensive reference covers all navigation techniques, from basic panel switching to advanced power-user workflows.

{% hint style="info" %}
**Quick Reference Needed?** Jump to the Complete Shortcut Reference at the bottom of this page.
{% endhint %}

### Navigation Philosophy

Gonzo's navigation is designed around three core principles:

1. **🎯 Efficiency** - Common actions have single-key shortcuts
2. **🔄 Consistency** - Same shortcuts work across similar contexts
3. **🖱️ Flexibility** - Both keyboard and mouse work seamlessly

The interface supports both **vim-style navigation** (hjkl) and **arrow keys**, plus **point-and-click** for users who prefer mouse interaction.

### Global Navigation

These shortcuts work from anywhere in Gonzo:

#### Essential Global Shortcuts

| Key                | Action               | Description                   | Pro Tip                         |
| ------------------ | -------------------- | ----------------------------- | ------------------------------- |
| **Tab**            | Next panel           | Move clockwise through panels | Fastest way to switch focus     |
| **Shift+Tab**      | Previous panel       | Move counter-clockwise        | Reverse direction navigation    |
| **Space**          | Global pause/unpause | Freeze entire dashboard       | Use to examine data closely     |
| **q** / **Ctrl+C** | Quit Gonzo           | Exit application              | Always works, even from modals  |
| **?** / **h**      | Show help            | Display help overlay          | Quick reference without leaving |
| **r**              | Reset all data       | Clear analysis, restart       | Fresh start with same config    |

#### Advanced Global Controls

| Key   | Action                            | Description                         | When to Use                       |
| ----- | --------------------------------- | ----------------------------------- | --------------------------------- |
| **u** | Cycle update intervals (forward)  | 1s → 2s → 5s → 10s                  | Slow down for high-volume logs    |
| **U** | Cycle update intervals (backward) | 10s → 5s → 2s → 1s                  | Speed up for real-time monitoring |
| **c** | Toggle Host/Service columns       | Show/hide extra columns in log view | Adjust for terminal width         |
| **m** | Switch AI model                   | Open model selection modal          | Change AI provider on the fly     |

{% tabs %}
{% tab title="Panel Navigation" %}
**Moving Between Panels:**

```
┌─────────────────────┬─────────────────────┐
│ 1. Log Viewer   ←──→│ 2. Word Frequency   │
│    (Tab from 4)     │    (Tab from 1)     │
│         ↑           │         ↓           │
│         │           │         │           │
│         │           │         │           │
│         ↓           │         ↑           │
├─────────────────────┼─────────────────────┤
│ 4. Counts       ←──→│ 3. Attributes       │
│    (Tab from 3)     │    (Tab from 2)     │
└─────────────────────┴─────────────────────┘
```

**Order:** Log Viewer → Word Frequency → Attributes → Counts → repeat\
**Reverse:** Use `Shift+Tab` to go backwards through this cycle
{% endtab %}

{% tab title="Mouse Navigation" %}
**Click to Focus:**

* Click anywhere in a panel to focus it immediately
* No need to Tab through panels - just click where you want to go
* Mouse wheel works in focused panels for scrolling

**Mouse + Keyboard Combo:**

* Click to focus, then use keyboard for precise navigation
* Best of both worlds for different interaction styles
  {% endtab %}
  {% endtabs %}

### Panel-Specific Navigation

Each panel has specialized navigation optimized for its content:

#### Log Viewer (Top Left)

**Basic Movement:**

| Key                | Action           | Description                               |
| ------------------ | ---------------- | ----------------------------------------- |
| **↑/↓** or **k/j** | Move up/down     | Navigate through log entries line by line |
| **Page Up/Down**   | Jump by pages    | Navigate by 10 entries at a time          |
| **Home**           | Jump to top      | Go to oldest log (stops auto-scroll)      |
| **End**            | Jump to bottom   | Go to newest log (resumes auto-scroll)    |
| **Enter**          | View log details | Open detailed modal for selected entry    |

**Smart Auto-Scroll Behavior:**

```bash
# Auto-scroll is ACTIVE when:
- You're at the bottom of the log list
- New logs appear automatically
- Status shows "Following" or "Live"

# Auto-scroll PAUSES when:
- You navigate up from the bottom
- You use Home, Page Up, or ↑ keys
- Status shows "Paused" indicator

# Auto-scroll RESUMES when:
- You press End to jump to bottom
- You scroll down to the latest entry
- You press Space to unpause globally
```

**Advanced Log Navigation:**

| Key                 | Action              | Use Case                                 |
| ------------------- | ------------------- | ---------------------------------------- |
| **Mouse Wheel**     | Scroll up/down      | Quick browsing through logs              |
| **Click log entry** | Select specific log | Jump to particular entry                 |
| **Shift+Click**     | Range selection     | Select multiple entries (future feature) |

{% hint style="success" %}
**Pro Tip:** Use `Home` to jump to the beginning of your log buffer, then `End` to return to live mode. This is perfect for comparing current issues with earlier events.
{% endhint %}

#### Word Frequency (Top Right)

| Key                | Action               | Description                       |
| ------------------ | -------------------- | --------------------------------- |
| **↑/↓** or **k/j** | Navigate word list   | Browse through frequency rankings |
| **Enter**          | Filter by word       | Apply selected word as log filter |
| **Click word**     | Quick filter         | Mouse alternative to Enter        |
| **Mouse Wheel**    | Scroll through words | Browse long frequency lists       |

**Filtering Workflow:**

1. Focus Word Frequency panel (`Tab` to navigate there)
2. Use arrows to highlight interesting word
3. Press `Enter` to filter logs containing that word
4. Press `/` and clear filter to return to all logs

#### Attributes (Bottom Left)

| Key                 | Action              | Description                           |
| ------------------- | ------------------- | ------------------------------------- |
| **↑/↓** or **k/j**  | Browse attributes   | Navigate through key-value pairs      |
| **Enter**           | Search by attribute | Filter logs containing this attribute |
| **Click attribute** | Quick search        | Mouse alternative to Enter            |
| **Mouse Wheel**     | Scroll attributes   | Browse through longer attribute lists |

**Real-time Updates:**

* Attributes panel updates based on **currently selected log** in Log Viewer
* Navigate through logs to see how attributes change
* Perfect for correlating structured data with specific log entries

#### Counts (Bottom Right)

| Key             | Action              | Description                        |
| --------------- | ------------------- | ---------------------------------- |
| **Enter**       | Open analysis modal | View detailed patterns and heatmap |
| **Click panel** | Open analysis modal | Mouse alternative to Enter         |

**Analysis Modal Navigation:**

| Key                | Action           | Description                           |
| ------------------ | ---------------- | ------------------------------------- |
| **↑/↓** or **k/j** | Scroll content   | Navigate through analysis sections    |
| **Page Up/Down**   | Jump by sections | Quick movement through large analysis |
| **Mouse Wheel**    | Scroll smoothly  | Alternative to keyboard scrolling     |
| **ESC**            | Close modal      | Return to main dashboard              |

### Filtering and Search Navigation

#### Filter Mode

| Key        | Action            | Description                                |
| ---------- | ----------------- | ------------------------------------------ |
| **/**      | Enter filter mode | Type regex patterns to filter logs         |
| **ESC**    | Exit filter mode  | Cancel filter input, return to normal mode |
| **Enter**  | Apply filter      | Activate the typed filter pattern          |
| **Ctrl+C** | Clear filter      | Remove current filter and show all logs    |

**Filter Mode Workflow:**

```bash
1. Press '/' from any panel
2. Type your regex pattern (e.g., "error", "level.*warn")
3. Press Enter to apply
4. Use normal navigation on filtered results
5. Press '/' again and clear to remove filter
```

#### Search and Highlight

| Key     | Action         | Description                             |
| ------- | -------------- | --------------------------------------- |
| **s**   | Search mode    | Find and highlight text in current view |
| **n**   | Next match     | Jump to next highlighted occurrence     |
| **N**   | Previous match | Jump to previous highlighted occurrence |
| **ESC** | Clear search   | Remove highlighting and exit search     |

**Search vs Filter:**

* **Filter (/)**: Shows only matching logs, hides others
* **Search (s)**: Highlights matches but shows all logs

### Modal Navigation

Several features open detailed modals that have their own navigation:

#### Log Details Modal

**Opened by:** Pressing `Enter` on a log entry in Log Viewer

| Key                | Action                | Description                                 |
| ------------------ | --------------------- | ------------------------------------------- |
| **↑/↓** or **k/j** | Scroll content        | Navigate through log details                |
| **Tab**            | Switch between panels | Toggle between log details and chat         |
| **i**              | AI analysis           | Get intelligent insights (if AI configured) |
| **c**              | Start AI chat         | Interactive chat about current log          |
| **m**              | Switch AI model       | Change AI model without closing modal       |
| **ESC**            | Close modal           | Return to main dashboard                    |

#### AI Analysis Modal

**Opened by:** Pressing `i` in log details or using AI features

| Key                | Action              | Description                               |
| ------------------ | ------------------- | ----------------------------------------- |
| **↑/↓** or **k/j** | Navigate analysis   | Scroll through AI insights                |
| **Tab**            | Switch sections     | Move between analysis and recommendations |
| **Enter**          | Interactive prompts | Respond to AI questions (if available)    |
| **m**              | Switch model        | Change AI model mid-analysis              |
| **ESC**            | Close analysis      | Return to previous view                   |

#### Model Selection Modal

**Opened by:** Pressing `m` anywhere in the interface

| Key                | Action           | Description                          |
| ------------------ | ---------------- | ------------------------------------ |
| **↑/↓** or **k/j** | Navigate models  | Browse available AI models           |
| **Page Up/Down**   | Jump by sections | Quick navigation through many models |
| **Enter**          | Select model     | Switch to highlighted model          |
| **ESC**            | Cancel selection | Keep current model, close modal      |
| **Mouse Wheel**    | Scroll models    | Alternative to keyboard navigation   |

### Advanced Navigation Techniques

#### Power User Workflows

{% tabs %}
{% tab title="Quick Problem Investigation" %}
**Scenario:** You notice errors in Word Frequency

```bash
1. Tab to Word Frequency panel
2. Navigate to "error" entry with ↑/↓
3. Press Enter to filter logs
4. Tab to Log Viewer to see filtered results  
5. Navigate through errors with ↑/↓
6. Press Enter on suspicious entry for details
7. Press 'i' for AI analysis if configured
```

{% endtab %}

{% tab title="Pattern Analysis Workflow" %}
**Scenario:** Investigating recurring issues

```bash
1. Tab to Counts panel
2. Press Enter to open analysis modal
3. Use ↑/↓ to browse pattern analysis
4. Note interesting patterns
5. Press ESC to close modal
6. Use '/' to filter for specific patterns
7. Tab to Log Viewer to examine instances
```

{% endtab %}

{% tab title="Multi-Source Correlation" %}
**Scenario:** Correlating events across services

```bash
1. Start with Space to pause live feed
2. Tab to Attributes panel
3. Look for trace_id or correlation_id
4. Press Enter to search by that attribute
5. Navigate through correlated logs
6. Use Home/End to see time sequence
7. Space to resume live monitoring
```

{% endtab %}
{% endtabs %}

#### Efficiency Tips

**🚀 Speed Navigation:**

* Learn the Tab cycle: Log → Words → Attributes → Counts → repeat
* Use Home/End for quick time-based navigation
* Master Space for pause/unpause during investigation

**🎯 Context Switching:**

* Click panels for instant focus switching
* Use mouse wheel + keyboard combo for best of both worlds
* Remember ESC always gets you out of modals

**🔍 Search Strategy:**

* Start broad with Word Frequency filtering
* Narrow down with regex filters (/)
* Use search (s) for highlighting without filtering
* Combine with AI analysis (i) for insights

### Customization Options

#### Update Interval Control

Adjust how often the interface refreshes:

```bash
# Real-time monitoring (default)
u → 1s updates (most responsive)

# Balanced performance  
u → 2s updates (good balance)

# Resource conservation
u → 5s updates (lighter on system)

# Slow analysis
u → 10s updates (minimal resource usage)
```

#### Display Customization

```bash
# Toggle extra columns on/off
c → Show/hide Host and Service columns

# Helpful for:
- Narrow terminals (hide columns)
- Wide terminals (show more context)
- Focus on log content vs metadata
```

### Accessibility Features

#### Visual Indicators

* **Focus highlighting** - Current panel has distinct border
* **Selection highlighting** - Current item is clearly marked
* **Color coding** - Severity levels use consistent colors
* **Progress indicators** - Loading states and scroll positions

#### Alternative Navigation

* **Mouse support** - Full click navigation for users who prefer pointing
* **Arrow key alternatives** - Both hjkl (vim) and arrow keys work
* **Multiple ways to same action** - keyboard shortcuts + mouse + menu options

### Troubleshooting Navigation Issues

#### Terminal Size Issues

```bash
# Minimum recommended: 80x24
# Optimal: 120x40 or larger

# If interface looks cramped:
- Resize terminal window
- Use 'c' to hide extra columns
- Focus on single panel analysis
```

#### Key Conflicts

```bash
# If shortcuts don't work:
- Check terminal key mappings
- Try alternative shortcuts (arrows vs hjkl)
- Use mouse navigation as backup

# Common conflicts:
- Ctrl+C (might be intercepted by terminal)
- Tab (might be intercepted by shell)
- Use mouse clicking as alternative
```

#### Performance Issues

```bash
# If navigation feels sluggish:
- Use 'u' to increase update interval (2s or 5s)
- Use 'r' to reset data and clear memory
- Filter logs early to reduce processing

# For high-volume logs:
- Pause with Space during analysis
- Use larger buffers: --log-buffer=5000
- Filter at source when possible
```

### Complete Shortcut Reference

#### Global Shortcuts

| Key                     | Action                      | Context |
| ----------------------- | --------------------------- | ------- |
| **Tab** / **Shift+Tab** | Navigate panels             | Always  |
| **Space**               | Pause/unpause dashboard     | Always  |
| **q** / **Ctrl+C**      | Quit                        | Always  |
| **/**                   | Filter mode                 | Always  |
| **s**                   | Search and highlight        | Always  |
| **r**                   | Reset data                  | Always  |
| **u** / **U**           | Cycle update intervals      | Always  |
| **c**                   | Toggle Host/Service columns | Always  |
| **m**                   | Switch AI model             | Always  |
| **?** / **h**           | Show help                   | Always  |

#### Panel Navigation

| Key                | Action             | Context       |
| ------------------ | ------------------ | ------------- |
| **↑/↓** or **k/j** | Move up/down       | Any list      |
| **Page Up/Down**   | Jump by pages      | Any list      |
| **Home** / **End** | Jump to top/bottom | Any list      |
| **Enter**          | Select/details     | Selected item |
| **Mouse Click**    | Focus/select       | Any panel     |
| **Mouse Wheel**    | Scroll             | Focused panel |

#### Modal Controls

| Key     | Action                | Context              |
| ------- | --------------------- | -------------------- |
| **ESC** | Close modal           | Any modal            |
| **Tab** | Switch modal sections | Multi-section modals |
| **i**   | AI analysis           | Log details          |
| **c**   | AI chat               | Log details          |

#### Advanced Features

| Key           | Action                     | Context       |
| ------------- | -------------------------- | ------------- |
| **n** / **N** | Next/previous search match | Search mode   |
| **Ctrl+C**    | Clear filter               | Filter active |

***

**Master these navigation techniques and you'll analyze logs with incredible efficiency!** 🚀 The key is building muscle memory for the Tab cycle and essential shortcuts like Space for pause/unpause.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.controltheory.com/backup/user-guide/navigation-and-controls.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.