# Reference

Welcome to the Gonzo reference documentation! This section provides comprehensive technical reference material for all aspects of Gonzo.

### Overview

The Reference section contains detailed specifications, complete lists, and quick-lookup information. Use this section when you need to:

* **Look up** a specific keyboard shortcut
* **Check** valid configuration options
* **Find** environment variable names
* **Review** version history and changes
* **Verify** exact syntax or values

### Quick Access

#### Need to find something fast?

**Keyboard shortcuts**: Keyboard Shortcuts\
**Configuration options**: Configuration Schema\
**Environment variables**: Environment Variables\
**Version history**: Changelog

### Reference Guides

#### Keyboard Shortcuts

Complete reference of all keyboard shortcuts and mouse interactions.

**What's inside**:

* Global shortcuts (Space, q, r, etc.)
* Panel navigation (Tab, arrow keys)
* Log viewer controls
* AI feature shortcuts
* Search and filter shortcuts
* Vim-style navigation
* Mouse support
* Quick reference card (printable)

**Use when**:

* Learning keyboard shortcuts
* Looking up a specific key
* Wanting to optimize your workflow
* Printing a cheat sheet

**Quick examples**:

```
Space    - Pause/Resume
Enter    - View details
/        - Filter logs
i        - AI analysis
m        - Switch AI model
```

#### Configuration Schema

Complete specification of the configuration file format.

**What's inside**:

* Full YAML schema
* All configuration options
* Valid value types and ranges
* Default values
* Complete examples
* Validation rules
* Best practices

**Use when**:

* Creating a config file
* Validating configuration syntax
* Understanding default values
* Checking valid ranges
* Troubleshooting config issues

**Quick example**:

```yaml
files:
  - "/var/log/app.log"
follow: true
update-interval: 2s
log-buffer: 2000
skin: dracula
```

#### Environment Variables

Complete reference of all environment variables.

**What's inside**:

* Gonzo-specific variables
* AI provider variables
* System variables
* Variable precedence
* Configuration examples
* Docker/Kubernetes usage
* Shell profile setup

**Use when**:

* Setting up environment
* Container deployments
* CI/CD pipelines
* Debugging configuration
* Checking precedence

**Quick examples**:

```bash
GONZO_FILES="/var/log/app.log"
GONZO_FOLLOW="true"
OPENAI_API_KEY="sk-..."
GONZO_AI_MODEL="gpt-4"
```

#### Changelog

Version history and release notes.

**What's inside**:

* All version releases
* New features by version
* Bug fixes
* Breaking changes
* Upgrade notes
* Known issues
* Roadmap

**Use when**:

* Checking what's new
* Planning upgrades
* Understanding changes
* Reviewing history
* Checking compatibility

**Latest version**: 0.1.6 (August 2024)

### How to Use This Section

#### As a Quick Reference

**Keep these open while working**:

* Keyboard Shortcuts - For quick lookups
* Print the quick reference card for your desk

**Bookmark for frequent use**:

* Configuration Schema - When editing config
* Environment Variables - When setting up

#### As Complete Documentation

**Read through for comprehensive understanding**:

* Start with Configuration Schema
* Learn all shortcuts in Keyboard Shortcuts
* Understand precedence in Environment Variables
* Track changes via Changelog

#### As Troubleshooting Aid

**When something's not working**:

1. Check Configuration Schema for valid values
2. Verify environment in Environment Variables
3. Review Changelog for known issues
4. Try shortcuts from Keyboard Shortcuts

### Common Lookup Tasks

#### Find a Keyboard Shortcut

**Question**: "How do I pause the dashboard?"

**Answer**: Check Keyboard Shortcuts → Global Shortcuts

* `Space` - Pause/Resume

#### Validate Config Setting

**Question**: "What values can `update-interval` have?"

**Answer**: Check Configuration Schema → Performance Settings

* Type: `duration`
* Examples: `"500ms"`, `"1s"`, `"2s"`, `"5s"`

#### Find Environment Variable

**Question**: "How do I set the log buffer size via environment?"

**Answer**: Check Environment Variables → Performance Settings

* `GONZO_LOG_BUFFER="2000"`

#### Check Version Changes

**Question**: "What's new in version 0.1.6?"

**Answer**: Check Changelog → \[0.1.6]

* Full screen log viewing (`f` key)
* Extended search character limit
* OTLP message size increase

### Configuration Priority

Understanding how configuration is applied:

**Priority Order** (highest to lowest):

1. **Command line flags** - `gonzo --update-interval=2s`
2. **Environment variables** - `GONZO_UPDATE_INTERVAL="2s"`
3. **Configuration file** - `~/.config/gonzo/config.yml`
4. **Default values** - Built-in defaults

**Example**:

```bash
# config.yml says: update-interval: 10s
export GONZO_UPDATE_INTERVAL="5s"
gonzo --update-interval=1s
# Result: Uses 1s (flag overrides all)
```

Learn more in Configuration Schema and Environment Variables.

### Quick Reference Cards

#### Configuration Quick Card

```yaml
# Essential configuration
files: ["/var/log/app.log"]
follow: true
update-interval: 2s
log-buffer: 2000
memory-size: 15000
skin: dracula
ai-model: "gpt-4"
```

#### Environment Quick Card

```bash
# Essential environment variables
export GONZO_FILES="/var/log/app.log"
export GONZO_FOLLOW="true"
export GONZO_UPDATE_INTERVAL="2s"
export OPENAI_API_KEY="sk-..."
export GONZO_AI_MODEL="gpt-4"
```

#### Keyboard Quick Card

```
ESSENTIAL KEYS
─────────────
Space    Pause/Resume
q        Quit
/        Filter
s        Search
Enter    View details
ESC      Cancel/Close
i        AI analysis
m        Switch model
```

### Version Information

**Current Version**: 0.1.6\
**Release Date**: August 27, 2024\
**Go Version**: 1.21+ required\
**License**: MIT

See Changelog for complete version history.

### Compatibility

#### Platform Support

* **Linux**: All major distributions
* **macOS**: 10.15 and later
* **Windows**: Windows 10+ (WSL recommended)

#### Terminal Compatibility

**Recommended**:

* iTerm2 (macOS)
* Alacritty (Cross-platform)
* Windows Terminal (Windows)
* GNOME Terminal (Linux)
* Kitty (Cross-platform)

**Requirements**:

* Minimum 80x24 size
* 256 color support
* UTF-8 encoding

#### Go Version

**Required**: Go 1.21 or higher (for building from source)

**Check version**:

```bash
go version
```

### Related Documentation

#### Configuration Guides

* **Configuration File Guide** - Detailed config guide
* **CLI Reference** - Command line options
* **Advanced Configuration** - Advanced topics

#### User Guides

* **Quick Start** - Get started quickly
* **Basic Usage** - Learn the basics
* **Navigation & Controls** - Master the interface

#### Technical Docs

* **Architecture Overview** - How Gonzo works
* **OTLP Protocol** - Protocol details
* **Extension Points** - Extending Gonzo

### Printable Resources

#### Cheat Sheets

Create your own cheat sheets from these pages:

**Keyboard Shortcuts**:

* Print the quick reference card
* Keep near your workstation

**Configuration Template**:

* Copy the complete example
* Customize for your needs

**Environment Setup**:

* Use shell profile templates
* Add to your `.bashrc` or `.zshrc`

### Contributing to Reference Docs

Found an error or missing information?

**How to help**:

* [Open an issue](https://github.com/control-theory/gonzo/issues) to report problems
* [Submit a PR](https://github.com/control-theory/gonzo/pulls) to fix errors
* Suggest improvements via [Discussions](https://github.com/control-theory/gonzo/discussions)

See Contributing Guidelines for details.

### Keeping Up to Date

#### Stay Current

**Watch for updates**:

* Star the [GitHub repository](https://github.com/control-theory/gonzo)
* Watch for release notifications
* Check Changelog regularly
* Follow [@ControlTheoryHQ](https://twitter.com/ControlTheoryHQ)

**Update Gonzo**:

```bash
# Via go install
go install github.com/control-theory/gonzo/cmd/gonzo@latest

# Via Homebrew
brew upgrade gonzo

# Check version
gonzo --version
```

### Support

#### Need Help?

**For reference questions**:

* Search this Reference section
* Check related documentation
* Look in Troubleshooting

**For other help**:

* [GitHub Discussions](https://github.com/control-theory/gonzo/discussions) - Q\&A
* [GitHub Issues](https://github.com/control-theory/gonzo/issues) - Bug reports
* Email: <support@controltheory.com>

### Feedback

#### Improve These Docs

Help make reference docs better:

**What works well**:

* Clear examples
* Complete coverage
* Easy navigation
* Quick lookups

**We're working on**:

* Searchability
* More examples
* Better organization
* Interactive demos

**Your feedback matters**: [Share suggestions →](https://github.com/control-theory/gonzo/discussions)

***

### Navigate Reference Docs

Choose what you need:

**⌨️ Keyboard Shortcuts** - All shortcuts and mouse actions

**⚙️ Configuration Schema** - Complete config file reference

**🌍 Environment Variables** - All environment variables

**📋 Changelog** - Version history and release notes

{% hint style="info" %}
**Pro Tip**: Bookmark the pages you reference most often. The Keyboard Shortcuts and Environment Variables pages are frequently accessed.
{% endhint %}