# TUI Navigation and Controls

This document provides a comprehensive guide to navigating and interacting with GemReader's terminal user interface.

## Basic Navigation

| Key                | Action                |
| ------------------ | --------------------- |
| `↑` or `k`         | Move up one line      |
| `↓` or `j`         | Move down one line    |
| `PgUp` or `Ctrl+U` | Move up one page      |
| `PgDn` or `Ctrl+D` | Move down one page    |
| `g` or `Home`      | Go to top of document |
| `G` or `End`       | Go to end of document |

## Dual Pane Interface

GemReader features a split-screen interface with two panes:

### Content Pane (Right)

- Main area for viewing and scrolling through the markdown document
- This is the default active pane when the application starts

### Table of Contents Pane (Left)

- Displays a hierarchy of document headings automatically generated from markdown headers
- Shows headers with proper indentation based on header level (`#`, `##`, `###`, etc.)

## Pane Navigation

- Use `Tab` to switch between TOC and content panes
- When in TOC pane, use `↑` or `↓` to navigate between table of contents entries
- Press `Enter` while in TOC pane to jump to the selected header in the content pane
- Header indentation reflects the header level (`#`, `##`, `###`, etc.)
- Selected entries in the TOC are marked with a `>` character

## Help System

- Press `h` or `?` to toggle help visibility
- The help information shows available navigation commands
- Help is displayed at the bottom of the screen
- The help text has a subtle gray color to distinguish it from content

## Visual Elements

### Border Indicators

- Active pane has a yellow border
- Inactive pane has a blue border

## Advanced Navigation Tips

1. **Quick Navigation**: Use `g` to jump to the beginning and `G` to jump to the end of the document.

2. **Page Navigation**: Use Page Up and Page Down keys to quickly move through longer documents.

3. **TOC Navigation**: Use Tab to switch to the TOC pane, navigate with arrow keys, and press Enter to jump to specific sections.

4. **Toggle Help**: Press `h` or `?` to hide help text if you need more screen space for reading.

## Screen Layout

The terminal interface is organized as follows:

1. **Table of Contents Pane** (left): Shows document structure with clickable headers
2. **Content Pane** (right): Main content area with the rendered markdown
3. **Help Text** (bottom): Shows navigation keys (when visible)

## Troubleshooting Navigation Issues

### Keys Not Responding

- Some terminals may not recognize certain key combinations
- Try using the alternative keys listed in the table above
- Ensure your terminal is not intercepting the key combinations

### Scrolling Issues with Large Documents

- Use Page Up/Page Down for faster navigation
- Use the table of contents (switch with Tab and navigate with arrows) to jump to specific sections
- Navigate to top (`g`) or bottom (`G`) for quick positioning