Upload files to "docs"

docs/navigation.md

@@ -0,0 +1,82 @@
+# 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