diff --git a/Basic-Usage.md b/Basic-Usage.md
new file mode 100644
index 0000000..ba53e2f
--- /dev/null
+++ b/Basic-Usage.md
@@ -0,0 +1,369 @@
+# Basic Usage
+
+Essential workflows and everyday usage patterns for TTYverse. This guide assumes you've completed [Getting Started](Getting-Started) and have TTYverse configured.
+
+## Daily Workflow
+
+### Starting TTYverse
+```bash
+# Start TTYverse
+./ttyverse.pl
+
+# TTYverse loads and shows:
+# - Current version and login status
+# - Recent timeline posts
+# - Direct messages (if any)
+# - Ready prompt: TTYverse>
+```
+
+### Reading Your Timeline
+When TTYverse starts, it automatically loads your home timeline:
+
+```
+a0> {,POST_ID} <username> (2h ago) via Web [Public]
+    Content of the post goes here with any links or hashtags
+
+a1> {,POST_ID} <username> (1h ago) via TTYverse [Unlisted]
+    Another post with different visibility
+```
+
+**Understanding the format:**
+- **a0**, **a1** - Menu codes for referencing posts
+- **username** - Who posted it
+- **(2h ago)** - How long ago it was posted
+- **via Web** - What client was used
+- **[Public]** - Visibility level
+
+### Loading More Content
+```bash
+# See more posts from timeline
+/again
+
+# Refresh timeline for new posts
+/refresh
+
+# See posts from cache
+/last 15
+```
+
+## Reading Different Timelines
+
+### Home Timeline (Default)
+Your personalized feed from accounts you follow:
+```bash
+/timeline          # Show home timeline
+```
+
+### Local Timeline
+Posts from your instance/server:
+```bash
+/timeline local    # See what your community is posting
+```
+
+### Federated Timeline
+Posts from across the fediverse:
+```bash
+/timeline federated    # See the broader conversation
+```
+
+### Bookmarks
+Posts you've saved:
+```bash
+/timeline bookmarks    # Your saved posts
+```
+
+## Interacting with Posts
+
+### Basic Interactions
+```bash
+# Like a post
+/fav a3
+
+# Share a post (boost/reblog)
+/boost a3
+
+# Save for later
+/bookmark a3
+
+# Reply to a post
+/reply a3 Great point about accessibility!
+```
+
+### Opening Links
+When posts contain URLs:
+```bash
+# Open the URL from post a3
+/url a3
+
+# TTYverse automatically detects your environment:
+# - GUI environment: Opens in Firefox, Chrome, etc.
+# - Terminal: Opens in w3m, elinks, or lynx
+```
+
+### Getting User Information
+```bash
+# Learn about a user
+/whois storm@stormux.org
+
+# Shows profile information, follower count, etc.
+```
+
+## Creating Content
+
+### Simple Text Posts
+```bash
+# Create a public post
+/post Just learned about TTYverse - loving the accessibility focus!
+
+# TTYverse creates the post and shows confirmation
+```
+
+### Posts with Media
+```bash
+# Upload an image
+/media ~/pictures/sunset.jpg
+
+# TTYverse will prompt for:
+# 1. Alt-text description (required for images)
+# 2. Optional post message
+```
+
+**Alt-text example:**
+```
+Enter alt text for sunset.jpg: Orange and purple clouds over mountains during golden hour
+Enter post message (optional): Beautiful evening hike in the local mountains
+```
+
+### Replying to Conversations
+```bash
+# Reply to someone's post
+/reply a5 That's exactly what I was thinking! Have you tried the new media upload feature?
+
+# Your reply appears in the conversation thread
+```
+
+## Managing Conversations
+
+### Direct Messages
+```bash
+# Check for direct messages
+/dms
+
+# Shows recent DMs:
+[DM da0][friend@instance.org] (1h ago)
+   Hey, saw your post about TTYverse - is it really that accessible?
+
+# Reply to a DM
+/reply da0 Yes! It's designed by a blind developer with accessibility as the top priority.
+```
+
+### Following Conversations
+```bash
+# Follow an interesting user
+/follow @username@instance.com
+
+# Their posts will appear in your home timeline
+```
+
+## Searching and Discovery
+
+### Finding Content
+```bash
+# Search for hashtags
+/search #accessibility
+
+# Find users
+/search storm@stormux.org
+
+# Search post content
+/search "command line fediverse"
+```
+
+### Exploring Communities
+```bash
+# See what your local instance is discussing
+/timeline local
+
+# Discover broader conversations
+/timeline federated
+
+# Find trending topics (if your server supports it)
+/search #trending
+```
+
+## Voting in Polls
+
+When you see a poll in your timeline, it appears with numbered options:
+
+```
+b3> {,POST_ID} <username> (30m ago) via Web [Public]
+    What's your favorite terminal editor?
+    
+    Poll (ends in 2 days, 15 votes):
+    1. vim (8 votes - 53%)
+    2. emacs (4 votes - 27%) 
+    3. nano (3 votes - 20%)
+```
+
+Vote using the menu code and option number:
+```bash
+# Vote for option 1 (vim)
+/vote b3 1
+
+# For multiple choice polls, vote for multiple options
+/vote b3 1,3
+```
+
+## Managing Your Experience
+
+### Adjusting Settings
+```bash
+# Change how often timeline refreshes (in seconds)
+/set effpause 300        # Refresh every 5 minutes
+
+# Set your preferred browsers
+/set gui_browser firefox
+/set cli_browser w3m
+
+# Check current settings
+/get effpause
+```
+
+### Getting Information
+```bash
+# See available commands
+/help
+
+# Check API rate limits
+/rate
+
+# See TTYverse version
+/version
+```
+
+### Controlling Output
+```bash
+# Enable detailed output
+/verbose
+
+# Enable debug information (for troubleshooting)
+/debug
+```
+
+## Sound Notifications
+
+TTYverse includes audio feedback for different events:
+
+- **New posts** - Gentle notification sound
+- **Mentions** - Distinctive alert when someone mentions you
+- **Direct messages** - Special sound for private messages
+- **Your posts** - Confirmation when your posts appear
+- **Boosts/favorites** - Feedback when others interact with your posts
+
+Sound files are stored in `~/.local/share/ttyverse/sounds/default/`
+
+## Common Workflows
+
+### Morning Routine
+```bash
+# Start TTYverse and catch up
+./ttyverse.pl           # Shows recent timeline
+/dms                    # Check direct messages
+/timeline local         # See community activity
+```
+
+### Active Participation
+```bash
+# Engage with interesting content
+/fav a3                 # Like interesting posts
+/boost a5               # Share good content
+/reply a7 Great insight! # Join conversations
+/post Today I learned... # Share your thoughts
+```
+
+### Content Creation
+```bash
+# Share a photo with proper accessibility
+/media ~/photo.jpg
+# Alt-text: "Golden retriever playing in autumn leaves"
+# Message: "Morning walk with the dog - beautiful fall colors!"
+```
+
+### Research and Discovery
+```bash
+# Explore topics
+/search #photography    # Find photography discussions
+/timeline federated     # See broader conversations
+/search @expert         # Find knowledgeable users
+/follow @expert@domain  # Follow interesting people
+```
+
+### End of Session
+```bash
+# Save interesting posts for later
+/bookmark a3
+/bookmark b7
+
+# Exit cleanly
+/quit
+```
+
+## Tips for Effective Usage
+
+### Navigation Tips
+1. **Use menu codes efficiently** - They're faster than scrolling
+2. **Bookmark interesting posts** - Save them for later reference
+3. **Follow local timeline** - Discover your community
+4. **Use search regularly** - Find conversations on topics you care about
+
+### Engagement Tips
+1. **Always provide alt-text** - TTYverse enforces this for good reason
+2. **Reply thoughtfully** - Add value to conversations
+3. **Use appropriate visibility** - Consider who should see your posts
+4. **Boost good content** - Help spread valuable information
+
+### Accessibility Tips
+1. **TTYverse is screen reader friendly** - All output is plain text
+2. **Sound notifications help** - Audio cues for different events
+3. **Consistent structure** - Posts always follow the same format
+4. **Keyboard-only navigation** - No mouse required anywhere
+
+### Performance Tips
+1. **Adjust refresh rate** - Slower connections benefit from longer intervals
+2. **Use /last command** - Access cached posts without network requests
+3. **Bookmark instead of searching** - Faster access to interesting content
+
+## Troubleshooting Common Issues
+
+### Timeline Issues
+```bash
+# Timeline won't load
+/refresh                # Force refresh
+# Check network: ping 8.8.8.8
+
+# Old posts showing
+/timeline               # Reload home timeline
+```
+
+### Interaction Problems
+```bash
+# Menu codes not working
+# Make sure you're using current codes (they change as new posts load)
+
+# Can't reply or boost
+# Check if post is still available: /url a3
+```
+
+### Media Upload Issues
+```bash
+# Image upload fails
+# Ensure file exists: ls -la ~/path/to/image.jpg
+# Check file size (8MB limit for images on most servers)
+# Provide meaningful alt-text (required!)
+```
+
+---
+
+**See also:** [Getting Started](Getting-Started) | [Commands Reference](Commands-Reference) | [Media Uploads](Media-Uploads)
+
+*Last updated: 2025-07-28*
\ No newline at end of file
diff --git a/Commands-Reference.md b/Commands-Reference.md
new file mode 100644
index 0000000..68d6f5c
--- /dev/null
+++ b/Commands-Reference.md
@@ -0,0 +1,287 @@
+# Commands Reference
+
+Complete reference for all TTYverse commands. Commands are entered at the `TTYverse>` prompt and always start with `/`.
+
+## Timeline & Navigation Commands
+
+### `/timeline [type]`
+Display timeline content.
+
+**Usage:**
+- `/timeline` - Show home timeline (default)
+- `/timeline local` - Show local instance timeline
+- `/timeline federated` - Show federated timeline  
+- `/timeline bookmarks` - Show bookmarked posts
+
+**Examples:**
+```bash
+/timeline                # Home timeline
+/timeline local          # Local posts
+/timeline federated      # All federated posts
+/timeline bookmarks      # Your bookmarks
+```
+
+### `/again`
+Show more posts from the current timeline.
+
+### `/refresh`
+Refresh the current timeline and fetch new posts.
+
+### `/last [number]`
+Show the last N posts from cache.
+
+**Example:**
+```bash
+/last 10    # Show last 10 posts
+```
+
+## Posting Commands
+
+### `/post <message>`
+Create a new public post.
+
+**Usage:**
+```bash
+/post Hello fediverse!
+/post This is a longer post with multiple words
+```
+
+**Note:** Posts default to public visibility.
+
+### `/reply <code> <message>`
+Reply to a specific post using its menu code.
+
+**Usage:**
+```bash
+/reply a3 Thanks for sharing!
+/reply b1 Great point about accessibility
+```
+
+### `/media <filepath> [message]`
+Upload media (image, audio, video) with optional post text.
+
+**Usage:**
+```bash
+/media /path/to/image.jpg              # Upload image only
+/media /path/to/audio.mp3 Great song!  # Upload with message
+```
+
+**Accessibility:** Images require alt-text descriptions. TTYverse will prompt for alt-text and cancel uploads without descriptions.
+
+**Supported formats:**
+- **Images:** JPEG, PNG, GIF, WebP
+- **Audio:** MP3, OGG, WAV, FLAC, M4A
+- **Video:** MP4, WebM, MOV
+
+## Interaction Commands
+
+### `/boost <code>`
+Boost (reblog) a post.
+
+**Usage:**
+```bash
+/boost a3    # Boost post a3
+/boost b7    # Boost post b7
+```
+
+### `/unboost <code>`
+Remove boost from a post.
+
+### `/fav <code>` / `/favorite <code>`
+Favorite (like) a post.
+
+**Usage:**
+```bash
+/fav a3      # Favorite post a3
+/favorite b1 # Same as /fav
+```
+
+### `/unfav <code>`
+Remove favorite from a post.
+
+### `/bookmark <code>`
+Bookmark a post for later.
+
+### `/unbookmark <code>`
+Remove bookmark from a post.
+
+### `/vote <code> <choices>`
+Vote in a poll.
+
+**Usage:**
+```bash
+/vote a3 1           # Vote for option 1
+/vote b2 2,3         # Vote for options 2 and 3 (multiple choice)
+/vote c1 1-3         # Vote for options 1 through 3
+```
+
+## Direct Messages
+
+### `/dms`
+Show recent direct messages.
+
+### `/reply <dm_code> <message>`
+Reply to a direct message.
+
+**Usage:**
+```bash
+/reply da1 Thanks for the message!
+```
+
+## Search Commands
+
+### `/search <query>`
+Search for posts, hashtags, or accounts.
+
+**Usage:**
+```bash
+/search #accessibility          # Search hashtag
+/search @username@instance.com   # Search user
+/search "climate change"         # Search text
+/search technology              # Search term
+```
+
+### `/whois <username>`
+Get information about a user.
+
+**Usage:**
+```bash
+/whois storm@stormux.org
+/whois @localuser
+```
+
+## Account & Profile Commands
+
+### `/follow <username>`
+Follow a user.
+
+**Usage:**
+```bash
+/follow storm@stormux.org
+/follow @localuser
+```
+
+### `/unfollow <username>`
+Unfollow a user.
+
+### `/block <username>`
+Block a user.
+
+### `/unblock <username>`
+Unblock a user.
+
+### `/mute <username>`
+Mute a user.
+
+### `/unmute <username>`
+Unmute a user.
+
+## URL & Link Commands
+
+### `/url <code>`
+Open URL from a post in your browser.
+
+**Usage:**
+```bash
+/url a3    # Open URL from post a3
+```
+
+TTYverse automatically detects your environment and uses:
+- **GUI browsers:** Firefox, Chrome, etc. (if DISPLAY is set)
+- **CLI browsers:** w3m, elinks, lynx (in terminal)
+
+**Configuration:**
+- Set `gui_browser` in config for GUI preference
+- Set `cli_browser` in config for CLI preference
+
+## Information Commands  
+
+### `/help`
+Show available commands.
+
+### `/version`
+Show TTYverse version information.
+
+### `/about`
+Show information about TTYverse.
+
+### `/rate`
+Show current API rate limit status.
+
+## Configuration Commands
+
+### `/set <option> <value>`
+Change configuration options.
+
+**Common options:**
+```bash
+/set effpause 60           # Set refresh interval (seconds)
+/set gui_browser firefox   # Set GUI browser
+/set cli_browser w3m       # Set CLI browser
+```
+
+### `/get <option>`
+Show current value of configuration option.
+
+## System Commands
+
+### `/quit` / `/exit`
+Exit TTYverse.
+
+### `/restart`
+Restart TTYverse (reload configuration).
+
+## Debug Commands
+
+### `/verbose`
+Toggle verbose output for debugging.
+
+### `/debug`
+Toggle debug output for troubleshooting.
+
+## Menu Codes
+
+TTYverse assigns menu codes to posts for easy reference:
+
+- **Posts:** `a0`, `a1`, `a2`, ... `a9`, `b0`, `b1`, etc.
+- **DMs:** `da0`, `da1`, `da2`, etc.
+
+Codes are assigned in chronological order, with newer posts getting later codes.
+
+## Visibility Levels
+
+When posting, content visibility is shown:
+- **[Public]** - Visible to everyone, appears in timelines
+- **[Unlisted]** - Public but not in local/federated timelines
+- **[Followers]** - Only followers can see
+- **[Direct]** - Only mentioned users can see
+
+## Command Aliases
+
+Some commands have shorter aliases:
+- `/fav` = `/favorite`
+- `/boost` = `/rt` = `/reblog`
+- `/dms` = `/dm`
+- `/quit` = `/exit` = `/q`
+
+## Tips
+
+1. **Tab completion:** Most commands support tab completion
+2. **Command history:** Use up/down arrows for command history
+3. **Multiple words:** Wrap multi-word arguments in quotes if needed
+4. **Case sensitivity:** Commands are case-insensitive
+5. **Menu codes:** Always use current menu codes (they change as new posts load)
+
+## Error Handling
+
+Common error messages:
+- "Invalid menu code" - Post code doesn't exist or is old
+- "Rate limit exceeded" - API calls too frequent, wait a moment
+- "Not found" - User or post doesn't exist
+- "Unauthorized" - Authentication problem, check OAuth setup
+
+---
+
+**See also:** [Getting Started](Getting-Started) | [Basic Usage](Basic-Usage) | [Advanced Features](Advanced-Features)
+
+*Last updated: 2025-07-28*
\ No newline at end of file
diff --git a/Configuration.md b/Configuration.md
new file mode 100644
index 0000000..4980db1
--- /dev/null
+++ b/Configuration.md
@@ -0,0 +1,322 @@
+# Configuration
+
+TTYverse stores configuration in XDG-compliant directories and supports extensive customization through configuration files and runtime settings.
+
+## Configuration Locations
+
+### XDG Base Directory Support
+TTYverse follows the XDG Base Directory Specification:
+
+- **Config files:** `$XDG_CONFIG_HOME/ttyverse/` or `~/.config/ttyverse/`
+- **Data files:** `$XDG_DATA_HOME/ttyverse/` or `~/.local/share/ttyverse/`
+- **Cache files:** `$XDG_CACHE_HOME/ttyverse/` or `~/.cache/ttyverse/`
+
+### Key Files
+```
+~/.config/ttyverse/
+├── ttyverse_rc          # Main configuration file
+├── oauth_credentials    # OAuth tokens (keep secure!)
+└── dm_seen_status       # Direct message tracking
+
+~/.local/share/ttyverse/
+├── extensions/          # Extension scripts
+│   ├── soundpack.pl     # Sound notifications
+│   ├── tts.pl          # Text-to-speech
+│   └── libnotify.pl    # Desktop notifications
+└── sounds/             # Sound notification files
+    └── default/        # Default sound pack
+        ├── default.ogg
+        ├── mention.ogg
+        ├── dm.ogg
+        └── ...
+```
+
+## Main Configuration File
+
+### ttyverse_rc Format
+The main config file (`~/.config/ttyverse/ttyverse_rc`) uses a simple key=value format:
+
+```perl
+# TTYverse Configuration File
+# Generated by TTYverse setup
+
+# Server and authentication
+apibase=https://your-instance.com/api/v1
+tokenkey=your_oauth_token_here
+
+# Display and behavior settings  
+effpause=120
+verbose=1
+readline=1
+
+# Browser settings
+gui_browser=firefox
+cli_browser=w3m
+
+# Extension settings
+extension_notify=default,mention,dm
+```
+
+### Key Configuration Options
+
+#### Core Settings
+- **`apibase`** - Your fediverse server's API base URL
+- **`tokenkey`** - OAuth authentication token (keep private!)
+- **`effpause`** - Timeline refresh interval in seconds (default: 120)
+- **`verbose`** - Enable verbose output (0/1)
+- **`readline`** - Enable advanced readline support (0/1)
+
+#### Browser Configuration
+- **`gui_browser`** - Preferred GUI browser (firefox, chrome, etc.)
+- **`cli_browser`** - Preferred CLI browser (w3m, elinks, lynx)
+
+#### Timeline Settings
+- **`timeline_count`** - Number of posts to fetch (default: 30)
+- **`timeline_cache`** - Maximum cached posts (default: 200)
+
+#### Notification Settings
+- **`extension_notify`** - Comma-separated list of notification types
+- **`sound_enabled`** - Enable sound notifications (0/1)
+
+## Browser Configuration
+
+TTYverse automatically detects your environment and chooses appropriate browsers:
+
+### GUI Environment (DISPLAY set)
+1. Uses `gui_browser` setting if configured
+2. Falls back to `xdg-open`
+3. Tries common browsers: firefox, chrome, chromium
+
+### CLI Environment (no DISPLAY)
+1. Uses `cli_browser` setting if configured  
+2. Tries CLI browsers: w3m, elinks, lynx
+
+### Manual Configuration
+```bash
+# Set browsers in TTYverse
+/set gui_browser firefox
+/set cli_browser w3m
+
+# Or edit config file directly
+echo "gui_browser=firefox" >> ~/.config/ttyverse/ttyverse_rc
+echo "cli_browser=w3m" >> ~/.config/ttyverse/ttyverse_rc
+```
+
+## Sound Configuration
+
+### Sound Pack Structure
+```
+~/.local/share/ttyverse/sounds/default/
+├── default.ogg      # General notifications
+├── mention.ogg      # When mentioned
+├── dm.ogg           # Direct messages  
+├── me.ogg          # Your own posts
+├── search.ogg       # Search results
+├── follow.ogg       # New followers
+├── boost.ogg        # When boosted
+├── favourite.ogg    # When favorited
+├── poll.ogg         # Poll notifications
+├── edit.ogg         # Edited posts
+└── announcement.ogg # Server announcements
+```
+
+### Sound Types
+TTYverse supports these notification types:
+- **default** - General notifications
+- **mention** - When someone mentions you
+- **dm** - Direct messages
+- **me** - Your own posts appearing in timeline
+- **search** - Search results
+- **follow** - New followers
+- **boost** - When someone boosts your post
+- **favourite** - When someone favorites your post
+- **poll** - Poll-related notifications
+- **edit** - When posts are edited
+- **announcement** - Server announcements
+
+### Custom Sound Packs
+Create custom sound packs by:
+1. Creating directory: `~/.local/share/ttyverse/sounds/mysounds/`
+2. Adding OGG files for each notification type
+3. Activating: `/set sound_pack mysounds`
+
+## Extension Configuration
+
+### Available Extensions
+- **soundpack.pl** - Sound notifications
+- **tts.pl** - Text-to-speech support
+- **libnotify.pl** - Desktop notifications
+- **timestamp.pl** - Enhanced timestamp display
+
+### Extension Management
+```bash
+# List loaded extensions
+ls ~/.local/share/ttyverse/extensions/
+
+# Check loaded extensions in TTYverse
+/verbose
+# Shows: ** loaded extensions: soundpack, tts
+```
+
+### Extension Settings
+Extensions can be configured through the main config file:
+```perl
+# Sound pack settings
+sound_enabled=1
+sound_pack=default
+
+# TTS settings  
+tts_enabled=1
+tts_voice=espeak
+
+# Notification settings
+notify_desktop=1
+notify_sound=1
+```
+
+## Runtime Configuration
+
+### Setting Options During Session
+```bash
+# View current setting
+/get effpause
+
+# Change setting
+/set effpause 60
+
+# View all settings
+/verbose
+```
+
+### Common Runtime Changes
+```bash
+# Adjust refresh rate
+/set effpause 300        # 5 minutes
+
+# Change browser  
+/set gui_browser chrome
+
+# Toggle verbose output
+/verbose
+
+# Toggle debug output
+/debug
+```
+
+## OAuth Configuration
+
+### OAuth Credential Files
+TTYverse stores OAuth credentials securely in:
+- **`oauth_credentials`** - Token and server information
+- **`ttyverse_rc`** - Main config with tokenkey
+
+### Re-authenticating
+If OAuth fails:
+```bash
+# Remove old credentials
+rm ~/.config/ttyverse/oauth_credentials
+rm ~/.config/ttyverse/ttyverse_rc
+
+# Restart TTYverse for fresh OAuth setup
+./ttyverse.pl
+```
+
+### Multiple Accounts
+TTYverse supports multiple accounts through keyfiles:
+```bash
+# Use different keyfile for second account
+./ttyverse.pl -keyfile work_account
+
+# This creates ~/.config/ttyverse/work_account_rc
+```
+
+## Performance Tuning
+
+### Memory Usage
+```perl
+# Reduce cached posts for lower memory usage
+timeline_cache=100
+
+# Reduce fetch count for slower connections
+timeline_count=15
+```
+
+### Network Settings
+```perl
+# Increase refresh interval for slower connections
+effpause=300
+
+# Reduce concurrent connections
+max_connections=2
+```
+
+### Accessibility Settings
+```perl
+# Force screen reader compatibility
+readline=1
+verbose=1
+
+# Enable all accessibility features
+sound_enabled=1
+alt_text_required=1
+```
+
+## Backup and Migration
+
+### Backing Up Configuration
+```bash
+# Backup entire config directory
+tar -czf ttyverse-config-backup.tar.gz ~/.config/ttyverse/
+
+# Backup just the main config
+cp ~/.config/ttyverse/ttyverse_rc ~/ttyverse_rc.backup
+```
+
+### Migration Between Systems
+1. Copy config directory to new system
+2. Update file paths if needed
+3. Re-authenticate if moving between different systems
+4. Install required dependencies (curl, perl modules)
+
+## Troubleshooting Configuration
+
+### Common Issues
+```bash
+# Config file not found
+ls -la ~/.config/ttyverse/
+# Create directory if missing: mkdir -p ~/.config/ttyverse/
+
+# Permission issues
+chmod 700 ~/.config/ttyverse/
+chmod 600 ~/.config/ttyverse/*
+
+# OAuth token issues
+# Check if token exists and is not empty
+cat ~/.config/ttyverse/ttyverse_rc | grep tokenkey
+```
+
+### Debug Configuration Loading
+```bash
+# Run with verbose output to see config loading
+./ttyverse.pl -verbose
+
+# Check which config file is being used
+./ttyverse.pl -debug
+```
+
+### Reset to Defaults
+```bash
+# Remove all configuration (will prompt for fresh setup)
+rm -rf ~/.config/ttyverse/
+rm -rf ~/.local/share/ttyverse/
+rm -rf ~/.cache/ttyverse/
+
+# Restart TTYverse
+./ttyverse.pl
+```
+
+---
+
+**See also:** [Getting Started](Getting-Started) | [Extensions](Extensions) | [Troubleshooting](Troubleshooting)
+
+*Last updated: 2025-07-28*
\ No newline at end of file
diff --git a/Extensions.md b/Extensions.md
new file mode 100644
index 0000000..f3df69e
--- /dev/null
+++ b/Extensions.md
@@ -0,0 +1,98 @@
+# Extensions
+
+TTYverse supports extensions that add functionality like sound notifications, text-to-speech, and desktop integration. Extensions are Perl scripts that integrate with TTYverse's multi-process architecture.
+
+## Available Extensions
+
+TTYverse includes several extensions that enhance the user experience:
+
+- **Sound Pack** - Audio notifications for different types of posts and events
+- **Text-to-Speech** - Speak posts and notifications aloud  
+- **Desktop Notifications** - Visual notification bubbles
+- **Timestamp Enhancement** - Enhanced timestamp display options
+
+Extensions are included with TTYverse but not enabled by default.
+
+## Extension Installation
+
+### Extension Availability
+TTYverse includes core extensions in the installation:
+
+```bash
+** attempting to load extensions
+** loading /home/user/.local/share/ttyverse/extensions/extensionname.pl
+** loaded extensions: extensionname
+```
+
+### Extension Location
+Extensions are stored in:
+```
+~/.local/share/ttyverse/extensions/
+```
+
+## Configuration
+
+Extensions are configured through TTYverse settings:
+
+```bash
+# View extension-related settings
+/get sound_enabled
+/get tts_enabled
+
+# Enable/disable extensions
+/set sound_enabled 1
+/set extension_name 0
+```
+
+Configuration can also be edited directly in:
+```
+~/.config/ttyverse/ttyverse_rc
+```
+
+## Extension Dependencies
+
+Some extensions may require additional system packages. Check the documentation for your specific distribution to install:
+
+- **Audio support** - PulseAudio or similar audio system
+- **Text-to-speech** - TTS engines like espeak or festival
+- **Desktop notifications** - libnotify and related Perl modules
+
+## Custom Extensions
+
+### Creating Extensions
+Extensions are Perl scripts that follow TTYverse conventions. They can:
+
+- Hook into post processing
+- React to different notification types  
+- Add new commands
+- Integrate with system features
+
+### Extension Development
+See the existing extensions in `~/.local/share/ttyverse/extensions/` for examples of how to create custom functionality.
+
+## Troubleshooting
+
+### Extension Issues
+```bash
+# Check if extensions are loading
+./ttyverse.pl -verbose
+
+# Test extension files manually  
+perl ~/.local/share/ttyverse/extensions/extensionname.pl
+
+# Fix permissions if needed
+chmod +x ~/.local/share/ttyverse/extensions/*.pl
+```
+
+### Common Problems
+- **Permission denied** - Make extension files executable
+- **Missing dependencies** - Install required system packages
+- **Configuration errors** - Check settings in ttyverse_rc
+
+For specific extension issues, check the [Troubleshooting](Troubleshooting) guide.
+
+---
+
+**See also:** [Configuration](Configuration) | [Troubleshooting](Troubleshooting) | [Installation](Installation)
+
+*Last updated: 2025-07-28*
\ No newline at end of file
diff --git a/FAQ.md b/FAQ.md
new file mode 100644
index 0000000..f2fdf79
--- /dev/null
+++ b/FAQ.md
@@ -0,0 +1,230 @@
+# Frequently Asked Questions (FAQ)
+
+Common questions about TTYverse. For technical issues, see [Troubleshooting](Troubleshooting).
+
+## General Questions
+
+### What is TTYverse?
+TTYverse is a command-line client for the fediverse (Mastodon, GoToSocial, etc.). It's designed for terminal users who want a powerful, accessible way to interact with ActivityPub servers.
+
+### How is TTYverse different from other fediverse clients?
+- **Accessibility-first design** - Built by and for screen reader users
+- **Terminal-native** - No GUI dependencies, works over SSH
+- **Single-file architecture** - Just one Perl script
+- **Sound notifications** - Audio feedback for different post types
+- **Enforced alt-text** - Images require descriptions for accessibility
+
+### What servers does TTYverse support?
+- **Mastodon** - Full support
+- **GoToSocial** - Full support  
+- **Pleroma** - Basic support
+- **Misskey** - Limited support
+- **Any ActivityPub server** - Basic federation features
+
+### Is TTYverse free?
+Yes, TTYverse is free software under the Floodgap Free Software License. You can use, modify, and distribute it freely.
+
+## Installation and Setup
+
+### Do I need to install anything besides TTYverse?
+You need Perl and curl, which are available on most Unix-like systems. Optional dependencies improve the experience:
+- **Term::ReadLine::Gnu** - Better command line editing
+- **PulseAudio** - Sound notifications
+- **w3m/elinks/lynx** - Opening links in terminal
+
+### Can I run TTYverse on Windows?
+Not directly. TTYverse is designed for Unix-like systems. You could try:
+- **WSL (Windows Subsystem for Linux)** - Run Linux environment on Windows
+- **Cygwin** - Unix-like environment for Windows
+- **Virtual machine** - Run Linux in a VM
+
+### How do I update TTYverse?
+Download the latest version and replace your current script:
+```bash
+wget -O ttyverse.pl https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
+chmod +x ttyverse.pl
+```
+
+## Usage Questions
+
+### How do I see older posts?
+Use `/again` to load more posts from your timeline, or `/last 20` to see the last 20 cached posts.
+
+### Can I use TTYverse over SSH?
+Yes! TTYverse works perfectly over SSH connections. Sound notifications won't work over SSH, but all other features do.
+
+### How do I open links from posts?
+Use `/url <post_code>` (e.g., `/url a3`). TTYverse will automatically detect your environment and use appropriate browsers.
+
+### Why does TTYverse require alt-text for images?
+TTYverse enforces accessibility standards. The maintainer is blind, and the philosophy is: "If you're going to use a client maintained by a blind guy, you can damn well describe your images!"
+
+### Can I post without media upload?
+Yes, use `/post Your message here` for text-only posts.
+
+## Technical Questions
+
+### Where does TTYverse store its configuration?
+TTYverse follows XDG Base Directory specification:
+- **Config:** `~/.config/ttyverse/`
+- **Data:** `~/.local/share/ttyverse/`
+- **Cache:** `~/.cache/ttyverse/`
+
+### How does the multi-process architecture work?
+TTYverse runs two processes:
+- **Foreground process** - User interface and commands
+- **Background process** - Timeline monitoring and data management
+
+They communicate via IPC (pipes and signals).
+
+### Can I run multiple instances?
+Yes, use different keyfiles:
+```bash
+./ttyverse.pl -keyfile work_account
+./ttyverse.pl -keyfile personal_account
+```
+
+### How do I backup my configuration?
+```bash
+tar -czf ttyverse-backup.tar.gz ~/.config/ttyverse/
+```
+
+## Features and Functionality
+
+### What timeline types are supported?
+- **Home timeline** - Posts from accounts you follow
+- **Local timeline** - Posts from your instance
+- **Federated timeline** - Posts from the broader fediverse
+- **Bookmarks** - Posts you've bookmarked
+
+### Does TTYverse support direct messages?
+Yes, use `/dms` to view direct messages and `/reply da1 message` to reply.
+
+### Can I boost and favorite posts?
+Yes:
+- `/boost a3` - Boost post a3
+- `/fav a3` - Favorite post a3
+- `/bookmark a3` - Bookmark post a3
+
+### What about search functionality?
+Use `/search` for:
+- `/search #hashtag` - Search hashtags
+- `/search @username` - Find users
+- `/search "text"` - Search post content
+
+## Accessibility Features
+
+### What accessibility features does TTYverse have?
+- **Screen reader friendly** - All output is text-based
+- **Sound notifications** - Audio feedback for events
+- **Alt-text enforcement** - Images must have descriptions
+- **Keyboard navigation** - No mouse required
+- **Terminal compatibility** - Works with any terminal
+
+### Can I disable sound notifications?
+Yes, edit `~/.config/ttyverse/ttyverse_rc` and set `sound_enabled=0`
+
+### Does TTYverse work with screen readers?
+Yes, TTYverse is designed specifically for screen reader users. All output is plain text and follows screen reader conventions.
+
+## Customization
+
+### Can I change the sound notifications?
+Yes, replace sound files in `~/.local/share/ttyverse/sounds/default/` or create custom sound packs.
+
+### How do I change the browser TTYverse uses?
+```bash
+/set gui_browser firefox
+/set cli_browser w3m
+```
+
+### Can I adjust the timeline refresh rate?
+```bash
+/set effpause 300    # Refresh every 5 minutes
+```
+
+### Are there extensions available?
+Yes, TTYverse includes several extensions:
+- **soundpack.pl** - Sound notifications
+- **tts.pl** - Text-to-speech
+- **libnotify.pl** - Desktop notifications
+
+## Troubleshooting
+
+### TTYverse won't start, what should I check?
+1. Perl is installed: `perl --version`
+2. curl is available: `curl --version`
+3. Script is executable: `chmod +x ttyverse.pl`
+4. Config directory exists: `mkdir -p ~/.config/ttyverse/`
+
+### I'm getting "connection failed" errors
+1. Check internet connection: `ping 8.8.8.8`
+2. Verify server URL in config
+3. Test server manually: `curl https://your-instance.com/api/v1/instance`
+4. Check firewall/proxy settings
+
+### OAuth setup isn't working
+1. Try manual OAuth - copy URL to browser manually
+2. Check browser configuration
+3. Verify server supports OAuth 2.0
+4. Clear old credentials and start fresh
+
+### Media uploads aren't working
+1. Check file size limits (8MB for images, 40MB for video on Mastodon)
+2. Verify file format is supported
+3. Test with smaller files
+4. Check server error messages
+
+## Development and Contributing
+
+### Can I contribute to TTYverse?
+Yes! Contributions are welcome:
+- Report bugs at https://git.stormux.org/storm/ttyverse/issues
+- Submit patches via email or git
+- Improve documentation
+- Create extensions
+
+### How is TTYverse developed?
+TTYverse is written in Perl as a single script. It's forked from TTYtter but completely rewritten for the fediverse.
+
+### Can I create extensions?
+Yes, extensions are Perl scripts in `~/.local/share/ttyverse/extensions/`. See existing extensions for examples.
+
+## Privacy and Security
+
+### What data does TTYverse store locally?
+- **OAuth tokens** - For server authentication
+- **Timeline cache** - Recent posts for faster display
+- **DM seen status** - To track read direct messages
+- **Configuration** - Your settings and preferences
+
+### How secure is TTYverse?
+- Uses OAuth 2.0 for authentication
+- Stores tokens locally with restricted permissions
+- No data sent to third parties
+- All communication is HTTPS
+
+### Can I run TTYverse without saving credentials?
+OAuth tokens must be saved for TTYverse to function. Tokens are stored with restricted file permissions (600).
+
+## Getting Help
+
+### Where can I get support?
+- **Built-in help:** `/help` command in TTYverse
+- **Documentation:** This wiki
+- **Issues:** https://git.stormux.org/storm/ttyverse/issues
+- **Community:** Fediverse community support
+
+### How do I report bugs?
+Report bugs at https://git.stormux.org/storm/ttyverse/issues with:
+- TTYverse version
+- System information
+- Steps to reproduce
+- Error messages
+- Debug output (if applicable)
+
+---
+
+**See also:** [Getting Started](Getting-Started) | [Troubleshooting](Troubleshooting) | [Commands Reference](Commands-Reference)
+
+*Last updated: 2025-07-28*
\ No newline at end of file
diff --git a/Getting-Started.md b/Getting-Started.md
new file mode 100644
index 0000000..31642d5
--- /dev/null
+++ b/Getting-Started.md
@@ -0,0 +1,232 @@
+# Getting Started with TTYverse
+
+TTYverse is a command-line fediverse client that lets you interact with Mastodon, GoToSocial, and other ActivityPub servers from your terminal. This guide will get you up and running quickly.
+
+## Prerequisites
+
+- **Perl 5.x** - TTYverse is written in Perl
+- **curl** - For API communication  
+- **Terminal emulator** - Any Unix/Linux terminal
+- **Fediverse account** - On Mastodon, GoToSocial, or compatible server
+
+## Installation
+
+### Quick Install
+```bash
+# Download the latest release
+wget https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
+
+# Make executable
+chmod +x ttyverse.pl
+
+# Run TTYverse
+./ttyverse.pl
+```
+
+For detailed installation options, see the [Installation](Installation) guide.
+
+## First-Time Setup
+
+### 1. Initial Launch
+When you first run TTYverse, it will guide you through OAuth setup:
+
+```bash
+./ttyverse.pl
+```
+
+### 2. Server Configuration
+TTYverse will ask for your fediverse server. Enter your instance URL:
+
+```
+Enter your fediverse instance (e.g., mastodon.social): your-instance.com
+```
+
+### 3. OAuth Authorization
+TTYverse will:
+1. Open your browser to authorize the application
+2. Generate an access token
+3. Save credentials to `~/.config/ttyverse/`
+
+### 4. First Login
+After setup, you'll see the TTYverse prompt:
+
+```
+TTYverse 2025.07.28 (c)2025 Storm Dragon
+fediverse client for Mastodon/GoToSocial/etc
+
+when ready, hit RETURN/ENTER for a prompt.
+type /help for commands or /quit to quit.
+
+TTYverse> 
+```
+
+## Essential Commands
+
+### Viewing Content
+```bash
+# Show your home timeline
+/timeline
+
+# Show local timeline
+/timeline local
+
+# Show federated timeline  
+/timeline federated
+
+# Show bookmarks
+/timeline bookmarks
+
+# Show direct messages
+/dms
+```
+
+### Creating Content
+```bash
+# Post a message
+/post Hello fediverse!
+
+# Reply to a post (using menu code)
+/reply a3 Thanks for the interesting post!
+
+# Post with media
+/media /path/to/image.jpg
+```
+
+### Interacting
+```bash
+# Boost a post
+/boost a3
+
+# Favorite a post  
+/fav a3
+
+# Vote in a poll
+/vote a3 2
+
+# Search
+/search #hashtag
+/search @username
+/search "search terms"
+```
+
+### Navigation
+```bash
+# Show more posts
+/again
+
+# Refresh timeline
+/refresh
+
+# Get help
+/help
+
+# Quit
+/quit
+```
+
+## Understanding Post Codes
+
+TTYverse assigns menu codes to posts for easy reference:
+
+```
+a0> {,POST_ID} <username> (2h ago) via TTYverse [Public]
+    This is a post with menu code 'a0'
+
+a1> {,POST_ID} <username> (1h ago) via Web [Unlisted]  
+    This post has menu code 'a1'
+```
+
+Use these codes with commands:
+- `/reply a0 Great post!`
+- `/boost a1`
+- `/fav a0`
+
+## Understanding Visibility Indicators
+
+Posts show visibility levels:
+- **[Public]** - Visible to everyone, appears in public timelines
+- **[Unlisted]** - Public but doesn't appear in local/federated timelines  
+- **[Followers]** - Only visible to your followers
+- **[Direct]** - Direct message, only visible to mentioned users
+
+## Media Uploads
+
+TTYverse enforces accessibility for images:
+
+```bash
+# Upload an image (will prompt for alt-text)
+/media /path/to/photo.jpg
+
+# Upload audio/video (no alt-text required)
+/media /path/to/audio.mp3
+```
+
+**Note:** Images require alt-text descriptions. TTYverse will cancel uploads without descriptions to enforce accessibility.
+
+## Sound Notifications
+
+TTYverse includes sound notifications for different events:
+- New posts
+- Mentions  
+- Direct messages
+- Boosts and favorites
+
+Sounds are stored in `~/.local/share/ttyverse/sounds/`
+
+## Configuration Files
+
+TTYverse stores configuration in XDG-compliant locations:
+- **Config:** `~/.config/ttyverse/`
+- **Extensions:** `~/.local/share/ttyverse/extensions/`
+- **Sounds:** `~/.local/share/ttyverse/sounds/`
+
+## Next Steps
+
+Once you're comfortable with basic usage:
+
+1. **[Configuration](Configuration)** - Customize TTYverse settings
+2. **[Advanced Features](Advanced-Features)** - Power user features
+3. **[Extensions](Extensions)** - Add sound packs and TTS
+4. **[Commands Reference](Commands-Reference)** - Complete command documentation
+
+## Common Issues
+
+### Connection Problems
+```bash
+# Test your connection
+/refresh
+
+# Check your OAuth setup
+cat ~/.config/ttyverse/ttyverse_rc
+```
+
+### Sound Issues
+```bash
+# Check if sound files exist
+ls ~/.local/share/ttyverse/sounds/default/
+
+# Test audio playback
+paplay ~/.local/share/ttyverse/sounds/default/default.ogg
+```
+
+### Permission Issues
+```bash
+# Ensure config directory is writable
+ls -la ~/.config/ttyverse/
+
+# Check file permissions
+chmod 600 ~/.config/ttyverse/*
+```
+
+## Getting Help
+
+- **In TTYverse:** Type `/help` for command list
+- **Troubleshooting:** See [Troubleshooting](Troubleshooting) guide
+- **FAQ:** Check [FAQ](FAQ) for common questions
+- **Issues:** Report bugs at https://git.stormux.org/storm/ttyverse/issues
+
+---
+
+**Next:** [Basic Usage](Basic-Usage) | [Commands Reference](Commands-Reference)
+
+*Last updated: 2025-07-28*
\ No newline at end of file
diff --git a/Home.md b/Home.md
index 70e57aa..0be2be5 100644
--- a/Home.md
+++ b/Home.md
@@ -1 +1,102 @@
-This is the central repository of knowledge about using TTYverse.
\ No newline at end of file
+# TTYverse Wiki
+
+**TTYverse** is a command-line fediverse client for Mastodon, GoToSocial, and other ActivityPub servers. Originally forked from TTYtter, it's been completely rebuilt for the fediverse era with accessibility and usability as core principles.
+
+## Quick Start
+
+**New to TTYverse?** → [Getting Started](Getting-Started) | [Installation](Installation)
+
+**Need help with a command?** → [Commands Reference](Commands-Reference) | [Quick Command List](Quick-Commands)
+
+**Having issues?** → [Troubleshooting](Troubleshooting) | [FAQ](FAQ)
+
+## Navigation
+
+### 📚 User Guides
+- **[Getting Started](Getting-Started)** - First-time setup and basic usage
+- **[Installation](Installation)** - Download, install, and initial configuration
+- **[Basic Usage](Basic-Usage)** - Essential commands and workflows
+- **[Advanced Features](Advanced-Features)** - Power user features and customization
+
+### 📖 Reference Documentation
+- **[Commands Reference](Commands-Reference)** - Complete command documentation
+- **[Configuration](Configuration)** - Settings, options, and customization
+- **[Keyboard Shortcuts](Keyboard-Shortcuts)** - Terminal navigation and hotkeys
+- **[File Locations](File-Locations)** - Config files, logs, and data storage
+
+### 🔧 Technical Documentation
+- **[Extensions](Extensions)** - Sound packs, TTS, and custom extensions
+- **[OAuth Setup](OAuth-Setup)** - Server authentication and key management
+- **[API Integration](API-Integration)** - Mastodon API usage and limitations
+- **[Architecture](Architecture)** - Multi-process design and IPC
+
+### 🆘 Support & Troubleshooting
+- **[Troubleshooting](Troubleshooting)** - Common issues and solutions
+- **[FAQ](FAQ)** - Frequently asked questions
+- **[Error Messages](Error-Messages)** - What error messages mean and how to fix them
+- **[Performance](Performance)** - Optimizing TTYverse for your system
+
+### 🎯 Feature Guides
+- **[Timeline Navigation](Timeline-Navigation)** - Reading posts, filtering, and browsing
+- **[Posting](Posting)** - Creating posts, replies, and using visibility settings
+- **[Media Uploads](Media-Uploads)** - Images, audio, video, and accessibility
+- **[Direct Messages](Direct-Messages)** - Private messaging and conversations
+- **[Polls](Polls)** - Creating and voting on polls
+- **[Search](Search)** - Finding posts, people, and hashtags
+
+### 🌐 Fediverse Integration
+- **[Server Compatibility](Server-Compatibility)** - Mastodon, GoToSocial, Pleroma support
+- **[Instance Features](Instance-Features)** - Feature differences across servers
+- **[Cross-Instance](Cross-Instance)** - Following and interacting across servers
+
+### 🔨 Development
+- **[Contributing](Contributing)** - How to contribute to TTYverse
+- **[Development Setup](Development-Setup)** - Setting up a development environment
+- **[Extension Development](Extension-Development)** - Creating custom extensions
+- **[Testing](Testing)** - Running tests and validation
+
+## Quick Reference
+
+### Essential Commands
+- `/help` - Show available commands
+- `/timeline` - Show timeline (home, local, federated, bookmarks)
+- `/post message` - Create a new post
+- `/reply a3 message` - Reply to post a3
+- `/boost a3` - Boost post a3
+- `/fav a3` - Favorite post a3
+- `/dms` - Show direct messages
+- `/media /path/file` - Upload media with post
+- `/search term` - Search posts and accounts
+- `/quit` - Exit TTYverse
+
+### Key Features
+- **🎵 Sound Notifications** - Audio feedback for different post types
+- **♿ Accessibility First** - Alt-text enforcement and screen reader friendly
+- **🔐 OAuth 2.0** - Secure authentication with any fediverse server
+- **⚡ Real-time Updates** - Background monitoring and notifications
+- **🎨 Extensions** - Sound packs, TTS, notifications, and more
+- **📱 Multi-format** - Text, images, audio, video, and polls
+
+## About TTYverse
+
+**Current Version:** 2025.07.28  
+**License:** Floodgap Free Software License  
+**Original:** Forked from TTYtter by Cameron Kaiser  
+**Maintainer:** Storm Dragon  
+**Repository:** https://git.stormux.org/storm/ttyverse
+
+### Philosophy
+> "If you're going to use a client maintained by a blind guy, you can damn well describe your images!"
+
+TTYverse prioritizes accessibility, usability, and the principles of the open fediverse. Every feature is designed with screen reader users and keyboard navigation in mind, while remaining powerful for all users.
+
+## Getting Help
+
+- **Commands:** Type `/help` in TTYverse for command list
+- **Issues:** Report bugs at https://git.stormux.org/storm/ttyverse/issues  
+- **Wiki:** This wiki for comprehensive documentation
+- **Community:** Find support in the fediverse community
+
+---
+
+*Last updated: 2025-07-28*
\ No newline at end of file
diff --git a/Installation.md b/Installation.md
new file mode 100644
index 0000000..0f38e2d
--- /dev/null
+++ b/Installation.md
@@ -0,0 +1,346 @@
+# Installation
+
+TTYverse is a single Perl script that works on any Unix-like system with Perl and curl. This guide covers installation methods for different systems.
+
+## System Requirements
+
+### Required
+- **Perl 5.x** - TTYverse is written in Perl
+- **curl** - For API communication with fediverse servers
+- **Terminal emulator** - Any Unix/Linux terminal
+
+### Recommended
+- **Term::ReadLine::Gnu** - Enhanced command line editing
+- **PulseAudio** - For sound notifications
+- **GUI browser** - For opening links (Firefox, Chrome, etc.)
+- **CLI browser** - For terminal link opening (w3m, elinks, lynx)
+
+### Optional
+- **Desktop notification system** - For desktop alerts
+- **Text-to-speech** - For TTS extensions
+
+## Installation Methods
+
+### Method 1: Direct Download (Recommended)
+
+```bash
+# Download latest release
+wget https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
+
+# Make executable
+chmod +x ttyverse.pl
+
+# Run TTYverse
+./ttyverse.pl
+```
+
+### Method 2: Git Clone
+
+```bash
+# Clone repository
+git clone https://git.stormux.org/storm/ttyverse.git
+cd ttyverse
+
+# Run TTYverse
+perl ttyverse.pl
+```
+
+### Method 3: System Package (Future)
+
+*System packages are planned for future releases*
+
+## Dependency Installation
+
+### Debian/Ubuntu
+```bash
+# Basic dependencies
+sudo apt update
+sudo apt install perl curl
+
+# Enhanced readline support
+sudo apt install libterm-readline-gnu-perl
+
+# Sound support
+sudo apt install pulseaudio-utils
+
+# Browser options
+sudo apt install firefox w3m
+
+# Optional: Desktop notifications
+sudo apt install libdesktop-notify-perl
+```
+
+### Arch Linux
+```bash
+# Basic dependencies
+sudo pacman -S perl curl
+
+# Enhanced readline support
+sudo pacman -S perl-term-readline-gnu
+
+# Sound support  
+sudo pacman -S pulseaudio
+
+# Browser options
+sudo pacman -S firefox w3m
+
+# Optional: AUR packages for additional features
+yay -S perl-desktop-notify
+```
+
+### Fedora/RHEL/CentOS
+```bash
+# Basic dependencies
+sudo dnf install perl curl
+
+# Enhanced readline support
+sudo dnf install perl-Term-ReadLine-Gnu
+
+# Sound support
+sudo dnf install pulseaudio-utils
+
+# Browser options
+sudo dnf install firefox w3m
+```
+
+### macOS
+```bash
+# Install Homebrew if not already installed
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Install dependencies
+brew install perl curl
+
+# Install optional dependencies
+brew install w3m
+
+# Note: macOS includes curl by default
+```
+
+### FreeBSD
+```bash
+# Install from ports
+sudo pkg install perl5 curl w3m
+
+# Or compile from ports
+cd /usr/ports/lang/perl5.32 && sudo make install clean
+cd /usr/ports/ftp/curl && sudo make install clean
+```
+
+## Installation Locations
+
+### Portable Installation
+TTYverse can run from any directory:
+```bash
+# Download to home directory
+cd ~
+wget https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
+chmod +x ttyverse.pl
+./ttyverse.pl
+```
+
+### System-wide Installation
+```bash
+# Install to /usr/local/bin for all users
+sudo wget -O /usr/local/bin/ttyverse https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
+sudo chmod +x /usr/local/bin/ttyverse
+
+# Now any user can run
+ttyverse
+```
+
+### Personal Binary Directory
+```bash
+# Install to personal bin directory
+mkdir -p ~/bin
+wget -O ~/bin/ttyverse https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
+chmod +x ~/bin/ttyverse
+
+# Add to PATH if needed
+echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+
+# Run from anywhere
+ttyverse
+```
+
+## Verification
+
+### Test Installation
+```bash
+# Check TTYverse version
+./ttyverse.pl -version
+
+# Expected output:
+# TTYverse 2025.07.28 (c)2025 Storm Dragon
+```
+
+### Test Dependencies
+```bash
+# Check Perl
+perl --version
+
+# Check curl
+curl --version
+
+# Check optional readline
+perl -MArray::ReadLine::Gnu -e 'print "ReadLine::Gnu available\n"' 2>/dev/null || echo "ReadLine::Gnu not available"
+
+# Check sound support
+paplay --version 2>/dev/null || echo "PulseAudio not available"
+```
+
+## First Run Setup
+
+### Initial Configuration
+When you first run TTYverse, it will:
+
+1. **Create config directories:**
+   ```
+   ~/.config/ttyverse/
+   ~/.local/share/ttyverse/
+   ```
+
+2. **Download extensions:**
+   - Sound pack extension
+   - TTS extension (if available)
+   - Notification extensions
+
+3. **OAuth setup:**
+   - Prompt for fediverse server
+   - Open browser for authorization
+   - Save authentication tokens
+
+### Manual Extension Setup
+```bash
+# Create extension directory
+mkdir -p ~/.local/share/ttyverse/extensions/
+
+# Download extensions manually if needed
+cd ~/.local/share/ttyverse/extensions/
+wget https://git.stormux.org/storm/ttyverse/raw/branch/master/extensions/soundpack.pl
+wget https://git.stormux.org/storm/ttyverse/raw/branch/master/extensions/tts.pl
+chmod +x *.pl
+```
+
+## Troubleshooting Installation
+
+### Permission Issues
+```bash
+# Make sure you can execute the script
+ls -la ttyverse.pl
+chmod +x ttyverse.pl
+
+# Check directory permissions
+ls -la ~/.config/
+mkdir -p ~/.config/ttyverse/
+chmod 700 ~/.config/ttyverse/
+```
+
+### Missing Dependencies
+```bash
+# Test if Perl modules are available
+perl -MHTml::Entities -e 'print "HTML::Entities available\n"'
+perl -MArray::JSON -e 'print "JSON available\n"'
+
+# Install missing Perl modules
+cpan HTML::Entities
+cpan JSON
+```
+
+### Network Issues
+```bash
+# Test network connectivity
+ping 8.8.8.8
+curl -I https://git.stormux.org/
+
+# Test SSL certificates
+curl https://mastodon.social/api/v1/instance
+```
+
+## Development Installation
+
+### For Contributors
+```bash
+# Clone development repository
+git clone https://git.stormux.org/storm/ttyverse.git
+cd ttyverse
+
+# Install development dependencies
+# (Add any dev-specific requirements here)
+
+# Run from source
+perl ttyverse.pl -verbose
+```
+
+### Building from Source
+```bash
+# TTYverse is a single script, no build process needed
+# Just ensure you have the latest version:
+
+cd ttyverse
+git pull origin master
+perl ttyverse.pl
+```
+
+## Uninstallation
+
+### Remove TTYverse
+```bash
+# Remove script
+rm ttyverse.pl
+# or
+sudo rm /usr/local/bin/ttyverse
+
+# Remove configuration (optional - saves your settings)
+rm -rf ~/.config/ttyverse/
+rm -rf ~/.local/share/ttyverse/
+rm -rf ~/.cache/ttyverse/
+```
+
+### Keep Configuration
+If you want to reinstall later, keep the config directories:
+```bash
+# Only remove the script
+rm ttyverse.pl
+
+# Configuration in ~/.config/ttyverse/ will be reused
+```
+
+## Updating
+
+### Manual Update
+```bash
+# Download new version
+wget -O ttyverse.pl.new https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
+
+# Backup old version
+mv ttyverse.pl ttyverse.pl.backup
+
+# Install new version
+mv ttyverse.pl.new ttyverse.pl
+chmod +x ttyverse.pl
+
+# Test new version
+./ttyverse.pl -version
+```
+
+### Git Update
+```bash
+# If installed via git
+cd ttyverse
+git pull origin master
+```
+
+### Version Check
+TTYverse checks for updates automatically:
+```
+-- checking TTYverse version...
+-- your version of TTYverse is up to date (2025.07.28)
+```
+
+---
+
+**Next:** [Getting Started](Getting-Started) | [Configuration](Configuration)
+
+*Last updated: 2025-07-28*
\ No newline at end of file
diff --git a/Media-Uploads.md b/Media-Uploads.md
new file mode 100644
index 0000000..e2a1ff5
--- /dev/null
+++ b/Media-Uploads.md
@@ -0,0 +1,244 @@
+# Media Uploads
+
+TTYverse supports uploading images, audio, and video files to your fediverse posts with a strong focus on accessibility.
+
+## Basic Usage
+
+### Upload Media with Post
+```bash
+/media /path/to/file.jpg Optional post message here
+```
+
+### Upload Media Only
+```bash
+/media /path/to/file.mp3
+```
+
+TTYverse will:
+1. Detect the file type automatically
+2. Prompt for alt-text (images only)
+3. Upload the media to your server
+4. Create a post with the media attached
+
+## Supported File Types
+
+### Images
+- **JPEG** (`.jpg`, `.jpeg`)
+- **PNG** (`.png`)
+- **GIF** (`.gif`)
+- **WebP** (`.webp`)
+
+### Audio  
+- **MP3** (`.mp3`)
+- **OGG** (`.ogg`)
+- **WAV** (`.wav`)
+- **FLAC** (`.flac`)
+- **M4A** (`.m4a`)
+
+### Video
+- **MP4** (`.mp4`)
+- **WebM** (`.webm`)
+- **MOV** (`.mov`)
+
+## Accessibility Requirements
+
+### Image Alt-Text (Required)
+
+TTYverse enforces alt-text for all images to ensure accessibility:
+
+```bash
+TTYverse> /media /home/user/photo.jpg
+-- Detected file type: image/jpeg
+-- Images require alt-text for accessibility
+Enter alt text for photo.jpg: A sunset over mountains with orange and purple clouds
+Enter post message (optional): Beautiful evening hike!
+-- Uploading media file...
+-- Media uploaded successfully
+-- Post created successfully!
+```
+
+### Alt-Text Guidelines
+
+**Good alt-text examples:**
+- "A golden retriever playing fetch in a park"
+- "Screenshot of terminal showing TTYverse timeline"
+- "Graph showing temperature increase over time"
+- "Person wearing red jacket standing on snowy mountain"
+
+**Avoid:**
+- Empty alt-text (upload will be cancelled)
+- Redundant phrases like "image of" or "picture showing"
+- File names or technical details
+- Vague descriptions like "thing" or "stuff"
+
+### Enforcement Message
+
+If you try to upload an image without alt-text:
+
+```
+-- Upload cancelled: Alt-text is required for images
+-- If you're going to use a client maintained by a blind guy, you can damn well describe your images!
+```
+
+This enforcement ensures TTYverse maintains its accessibility-first philosophy.
+
+## Audio and Video
+
+Audio and video files don't require alt-text, but you can still add descriptive post text:
+
+```bash
+/media /path/to/song.mp3 My latest recording - feedback welcome!
+/media /path/to/video.mp4 Time-lapse of sunset from my backyard
+```
+
+## File Size Limits
+
+Media upload limits depend on your fediverse server:
+
+- **Mastodon default:** 8MB for images, 40MB for video/audio
+- **GoToSocial:** Configurable by admin  
+- **Other servers:** Check your instance's upload limits
+
+TTYverse will show server error messages if files are too large.
+
+## Upload Process
+
+### Step-by-Step Flow
+
+1. **File Detection**
+   ```
+   -- Detected file type: image/jpeg
+   ```
+
+2. **Alt-Text Prompt** (images only)
+   ```
+   -- Images require alt-text for accessibility
+   Enter alt text for filename.jpg: [your description]
+   ```
+
+3. **Post Message** (optional)
+   ```
+   Enter post message (optional): [your message]
+   ```
+
+4. **Upload and Post**
+   ```
+   -- Uploading media file...
+   -- Media uploaded successfully (ID: xxxxxxxxx)
+   -- Creating post with media attachment...
+   -- Post created successfully!
+   ```
+
+### Background Processing
+
+TTYverse uploads happen in the foreground process while background monitoring continues. The multi-process architecture ensures:
+- Timeline updates don't interrupt uploads
+- Media uploads don't block timeline refresh
+- User can continue using TTYverse after posting
+
+## Error Handling
+
+### Common Upload Errors
+
+**File not found:**
+```
+-- ERROR: File not found: /path/to/missing.jpg
+```
+
+**Unsupported file type:**
+```
+-- ERROR: Unsupported file type: application/pdf
+-- Supported types: image/*, audio/*, video/*
+```
+
+**Server upload failure:**
+```
+-- ERROR: Media upload failed
+-- Response: {"error":"File too large"}
+```
+
+**Authentication errors:**
+```
+-- ERROR: No media ID in response  
+-- Response: {"error":"Unauthorized: token not supplied"}
+```
+
+### Troubleshooting
+
+**Authentication issues:**
+1. Check OAuth setup: `ls ~/.config/ttyverse/`
+2. Verify token: `/refresh` to test API access
+3. Re-authenticate if needed: `rm ~/.config/ttyverse/*` and restart
+
+**File permission issues:**
+1. Check file exists: `ls -la /path/to/file`
+2. Verify read permissions: `cat /path/to/file > /dev/null`
+3. Use absolute paths when possible
+
+**Server limits:**
+1. Check file size: `ls -lh /path/to/file`
+2. Try smaller files to test limits
+3. Check server documentation for upload limits
+
+## Best Practices
+
+### Alt-Text Writing
+- **Be concise but descriptive**
+- **Include relevant context** for the post
+- **Describe the important elements** that sighted users would notice
+- **Use natural language** as if describing to a friend
+
+### File Management
+- **Use descriptive filenames** for organization
+- **Keep files organized** in logical directories
+- **Check file sizes** before uploading
+- **Test uploads** with small files first
+
+### Accessibility Considerations
+- **Always provide meaningful alt-text** for images
+- **Include transcripts** in post text for audio content
+- **Describe video content** in post text when relevant
+- **Consider screen reader users** in all media posts
+
+## Examples
+
+### Image Post with Context
+```bash
+/media ~/photos/garden.jpg Tomatoes are finally ripening!
+# Alt-text: "Red and green tomatoes growing on vines in a garden"
+```
+
+### Audio with Description  
+```bash
+/media ~/recordings/bird-song.mp3 Recorded this morning in the park
+```
+
+### Video with Context
+```bash
+/media ~/videos/demo.mp4 Quick demo of the new feature working
+```
+
+### Technical Screenshot
+```bash
+/media ~/screenshots/terminal.png 
+# Alt-text: "Terminal window showing TTYverse commands and timeline with several posts visible"
+```
+
+## Integration with Fediverse
+
+### Server Compatibility
+- **Mastodon:** Full support for all media types
+- **GoToSocial:** Full support, admin-configurable limits
+- **Pleroma:** Basic support, check instance features
+- **Other servers:** Media support varies by implementation
+
+### Cross-Instance Media
+- Media uploads work with any compatible fediverse server
+- Alt-text is preserved when posts are viewed on other instances
+- Media appears in boosts and replies across the fediverse
+
+---
+
+**See also:** [Commands Reference](Commands-Reference) | [Accessibility](Accessibility) | [Server Compatibility](Server-Compatibility)
+
+*Last updated: 2025-07-28*
\ No newline at end of file
diff --git a/Quick-Commands.md b/Quick-Commands.md
new file mode 100644
index 0000000..a60cb79
--- /dev/null
+++ b/Quick-Commands.md
@@ -0,0 +1,152 @@
+# Quick Commands Reference
+
+Essential TTYverse commands for quick reference. For complete documentation, see [Commands Reference](Commands-Reference).
+
+## Essential Commands
+
+### Getting Started
+```bash
+/help                    # Show all available commands
+/timeline               # Show your home timeline
+/refresh                # Refresh timeline
+/quit                   # Exit TTYverse
+```
+
+### Posting and Interaction
+```bash
+/post Hello world!      # Create a public post
+/reply a3 Great point!  # Reply to post a3
+/boost a3               # Boost post a3
+/fav a3                 # Favorite post a3
+/bookmark a3            # Bookmark post a3
+```
+
+### Media and Content
+```bash
+/media /path/image.jpg  # Upload image (requires alt-text)
+/media /path/audio.mp3  # Upload audio file
+/url a3                 # Open URL from post a3
+```
+
+### Navigation
+```bash
+/timeline               # Home timeline
+/timeline local         # Local instance timeline
+/timeline federated     # Federated timeline
+/timeline bookmarks     # Your bookmarks
+/again                  # Load more posts
+/last 10                # Show last 10 cached posts
+```
+
+### Direct Messages
+```bash
+/dms                    # Show direct messages
+/reply da1 Thanks!      # Reply to DM da1
+```
+
+### Search and Discovery
+```bash
+/search #hashtag        # Search hashtag
+/search @username       # Find user
+/search "search text"   # Search posts
+/whois @username        # Get user info
+```
+
+### Account Management
+```bash
+/follow @user           # Follow a user
+/unfollow @user         # Unfollow a user
+/block @user            # Block a user
+/mute @user             # Mute a user
+```
+
+### Poll Interaction
+```bash
+/vote a3 1              # Vote for option 1 in poll a3
+/vote b2 2,3            # Vote for options 2 and 3
+```
+
+### Configuration
+```bash
+/set effpause 300       # Set refresh interval (5 minutes)
+/set gui_browser firefox # Set GUI browser
+/set cli_browser w3m    # Set CLI browser
+/get effpause           # Show current refresh interval
+```
+
+### Information
+```bash
+/version                # Show TTYverse version
+/rate                   # Show API rate limit status
+/verbose                # Toggle verbose output
+/debug                  # Toggle debug output
+```
+
+## Post Menu Codes
+
+TTYverse assigns codes to posts for easy reference:
+- **Timeline posts:** `a0`, `a1`, `a2`... `a9`, `b0`, `b1`, etc.
+- **Direct messages:** `da0`, `da1`, `da2`, etc.
+
+Use these codes with interaction commands:
+```bash
+/boost a3               # Boost post a3
+/reply b7 Nice post!    # Reply to post b7
+/url c2                 # Open URL from post c2
+```
+
+## Visibility Indicators
+
+Posts show their visibility level:
+- **[Public]** - Visible to everyone
+- **[Unlisted]** - Public but not in timelines
+- **[Followers]** - Only followers can see
+- **[Direct]** - Only mentioned users can see
+
+## Quick Tips
+
+1. **Use tab completion** - Start typing commands and press Tab
+2. **Command history** - Use up/down arrows for previous commands
+3. **Help anytime** - Type `/help` to see all commands
+4. **Menu codes change** - Always use current codes as new posts load
+5. **Alt-text required** - Images must have descriptions
+6. **Multiple timelines** - Switch between different timeline views
+
+## Common Workflows
+
+### Reading Timeline
+```bash
+/timeline               # Load home timeline
+/again                  # See more posts
+/url a3                 # Open interesting link
+/boost a5               # Share good post
+```
+
+### Posting with Media
+```bash
+/media ~/photo.jpg      # Upload image
+# Enter alt-text when prompted
+# Enter optional post message
+```
+
+### Engaging with Posts
+```bash
+/fav a3                 # Like the post
+/boost a3               # Share it
+/reply a3 Great point!  # Add your thoughts
+/bookmark a3            # Save for later
+```
+
+### Managing Timeline
+```bash
+/timeline bookmarks     # See saved posts
+/timeline local         # See local community
+/search #topic          # Find specific content
+/refresh                # Get latest posts
+```
+
+---
+
+**See also:** [Commands Reference](Commands-Reference) | [Getting Started](Getting-Started) | [Basic Usage](Basic-Usage)
+
+*Last updated: 2025-07-28*
\ No newline at end of file
diff --git a/Troubleshooting.md b/Troubleshooting.md
new file mode 100644
index 0000000..3513964
--- /dev/null
+++ b/Troubleshooting.md
@@ -0,0 +1,479 @@
+# Troubleshooting
+
+Common issues and solutions for TTYverse. If you don't find your issue here, check the [FAQ](FAQ) or report it at https://git.stormux.org/storm/ttyverse/issues.
+
+## Connection Issues
+
+### "Connection failed" or "Cannot connect to server"
+
+**Symptoms:**
+```
+-- ERROR: Connection failed
+-- Unable to fetch timeline
+```
+
+**Solutions:**
+1. **Check internet connection:**
+   ```bash
+   ping 8.8.8.8
+   curl -I https://google.com
+   ```
+
+2. **Verify server URL:**
+   ```bash
+   # Check your configured server
+   grep apibase ~/.config/ttyverse/ttyverse_rc
+   
+   # Test server manually
+   curl https://your-instance.com/api/v1/instance
+   ```
+
+3. **Check server status:**
+   - Visit your server's web interface
+   - Check server status pages
+   - Try different DNS servers
+
+4. **Firewall/proxy issues:**
+   ```bash
+   # Test if curl works
+   curl https://your-instance.com/api/v1/instance
+   
+   # Check proxy settings
+   echo $HTTP_PROXY
+   echo $HTTPS_PROXY
+   ```
+
+### SSL/TLS Certificate Issues
+
+**Symptoms:**
+```
+-- SSL certificate problem
+-- unable to get local issuer certificate
+```
+
+**Solutions:**
+1. **Update CA certificates:**
+   ```bash
+   # Debian/Ubuntu
+   sudo apt update && sudo apt install ca-certificates
+   
+   # Arch Linux
+   sudo pacman -S ca-certificates
+   ```
+
+2. **Check system time:**
+   ```bash
+   date
+   # Ensure system time is correct
+   ```
+
+3. **Test SSL manually:**
+   ```bash
+   openssl s_client -connect your-instance.com:443 -servername your-instance.com
+   ```
+
+## Authentication Issues
+
+### "Unauthorized" or "Token not supplied"
+
+**Symptoms:**
+```
+-- ERROR: Unauthorized: token not supplied
+-- Authentication failed
+```
+
+**Solutions:**
+1. **Check OAuth credentials:**
+   ```bash
+   # Verify token exists
+   cat ~/.config/ttyverse/ttyverse_rc | grep tokenkey
+   
+   # Check file permissions
+   ls -la ~/.config/ttyverse/
+   ```
+
+2. **Re-authenticate:**
+   ```bash
+   # Remove old credentials
+   rm ~/.config/ttyverse/oauth_credentials
+   rm ~/.config/ttyverse/ttyverse_rc
+   
+   # Restart TTYverse for fresh setup
+   ./ttyverse.pl
+   ```
+
+3. **Check token validity:**
+   ```bash
+   # Test token manually
+   TOKEN=$(grep tokenkey ~/.config/ttyverse/ttyverse_rc | cut -d= -f2)
+   curl -H "Authorization: Bearer $TOKEN" https://your-instance.com/api/v1/accounts/verify_credentials
+   ```
+
+### OAuth Setup Fails
+
+**Symptoms:**
+- Browser doesn't open during setup
+- "Failed to get authorization code"
+- OAuth redirect fails
+
+**Solutions:**
+1. **Manual OAuth setup:**
+   - Copy the authorization URL from TTYverse
+   - Open in browser manually
+   - Copy authorization code back to TTYverse
+
+2. **Check browser setup:**
+   ```bash
+   # Test browser detection
+   echo $DISPLAY
+   which xdg-open firefox chrome
+   ```
+
+3. **Alternative authentication:**
+   - Use different device for OAuth
+   - Try text-based browser
+   - Check server's OAuth settings
+
+## Performance Issues
+
+### Slow Timeline Loading
+
+**Symptoms:**
+- Long delays fetching posts
+- Timeouts during refresh
+
+**Solutions:**
+1. **Adjust refresh settings:**
+   ```bash
+   # Increase refresh interval
+   /set effpause 300
+   
+   # Reduce post count
+   /set timeline_count 15
+   ```
+
+2. **Check network speed:**
+   ```bash
+   # Test connection speed to server
+   time curl -I https://your-instance.com/
+   ```
+
+3. **Server performance:**
+   - Try different instance
+   - Check server status
+   - Use smaller media uploads
+
+### High Memory Usage
+
+**Symptoms:**
+- TTYverse consuming excessive RAM
+- System becoming unresponsive
+
+**Solutions:**
+1. **Reduce cache size:**
+   ```bash
+   # Edit config to reduce cached posts
+   echo "timeline_cache=50" >> ~/.config/ttyverse/ttyverse_rc
+   ```
+
+2. **Restart periodically:**
+   ```bash
+   # Exit and restart TTYverse
+   /quit
+   ./ttyverse.pl
+   ```
+
+3. **Monitor memory:**
+   ```bash
+   # Check TTYverse memory usage
+   ps aux | grep ttyverse
+   top -p $(pgrep ttyverse)
+   ```
+
+## Media Upload Issues
+
+### Media Upload Fails
+
+**Symptoms:**
+```
+-- ERROR: Media upload failed
+-- Response: {"error":"File too large"}
+```
+
+**Solutions:**
+1. **Check file size:**
+   ```bash
+   # Check file size
+   ls -lh /path/to/file
+   
+   # Common limits:
+   # Images: 8MB on Mastodon
+   # Video/Audio: 40MB on Mastodon
+   ```
+
+2. **Verify file format:**
+   ```bash
+   # Check MIME type
+   file --mime-type /path/to/file
+   
+   # Supported: image/*, audio/*, video/*
+   ```
+
+3. **Test with smaller file:**
+   ```bash
+   # Create test image
+   convert -size 100x100 xc:red test.jpg
+   /media test.jpg
+   ```
+
+### Alt-text Issues
+
+**Symptoms:**
+- Upload cancelled for images
+- Alt-text prompt not appearing
+
+**Solutions:**
+1. **Provide alt-text:**
+   - Always describe images meaningfully
+   - Don't leave alt-text empty
+   - Use descriptive, concise language
+
+2. **Check file type detection:**
+   ```bash
+   # Verify file is detected as image
+   file --mime-type /path/to/image.jpg
+   # Should show: image/jpeg
+   ```
+
+## Sound and Extension Issues
+
+### No Sound Notifications
+
+**Symptoms:**
+- Sound notifications not playing
+- Silent operation
+
+**Solutions:**
+1. **Check sound files:**
+   ```bash
+   # Verify sound files exist
+   ls ~/.local/share/ttyverse/sounds/default/
+   
+   # Test sound playback
+   paplay ~/.local/share/ttyverse/sounds/default/default.ogg
+   ```
+
+2. **Check audio system:**
+   ```bash
+   # Test system audio
+   speaker-test -c 2 -t wav
+   
+   # Check PulseAudio
+   pulseaudio --check
+   ```
+
+3. **Install sound dependencies:**
+   ```bash
+   # Install PulseAudio utils
+   sudo apt install pulseaudio-utils    # Debian/Ubuntu
+   sudo pacman -S pulseaudio           # Arch Linux
+   ```
+
+### Extension Loading Fails
+
+**Symptoms:**
+```
+** ERROR: Failed to load extension soundpack.pl
+```
+
+**Solutions:**
+1. **Check extension files:**
+   ```bash
+   # Verify extensions exist
+   ls ~/.local/share/ttyverse/extensions/
+   
+   # Check file permissions
+   chmod +x ~/.local/share/ttyverse/extensions/*.pl
+   ```
+
+2. **Install Perl dependencies:**
+   ```bash
+   # Common Perl modules needed
+   cpan Audio::Play::Simple
+   cpan Desktop::Notify
+   ```
+
+3. **Manual extension loading:**
+   ```bash
+   # Test extension manually
+   perl ~/.local/share/ttyverse/extensions/soundpack.pl
+   ```
+
+## Display and Terminal Issues
+
+### Readline Problems
+
+**Symptoms:**
+- No command history
+- No tab completion
+- Broken line editing
+
+**Solutions:**
+1. **Install Perl readline:**
+   ```bash
+   # Install Term::ReadLine::Gnu
+   sudo apt install libterm-readline-gnu-perl    # Debian/Ubuntu
+   cpan Term::ReadLine::Gnu                      # Manual install
+   ```
+
+2. **Check terminal compatibility:**
+   ```bash
+   # Verify terminal type
+   echo $TERM
+   
+   # Test readline
+   perl -MArray::ReadLine::Gnu -e 'print "Readline available\n"'
+   ```
+
+3. **Alternative terminals:**
+   - Try different terminal emulator
+   - Use screen or tmux
+   - Check terminal settings
+
+### Character Encoding Issues
+
+**Symptoms:**
+- Garbled text
+- Unicode characters display incorrectly
+- Emoji problems
+
+**Solutions:**
+1. **Check locale settings:**
+   ```bash
+   # Verify UTF-8 locale
+   locale
+   echo $LANG
+   
+   # Set UTF-8 if needed
+   export LANG=en_US.UTF-8
+   export LC_ALL=en_US.UTF-8
+   ```
+
+2. **Terminal encoding:**
+   - Ensure terminal supports UTF-8
+   - Check terminal preferences
+   - Try different terminal emulator
+
+## Configuration Issues
+
+### Config File Not Found
+
+**Symptoms:**
+```
+-- Config file not found
+-- Using defaults
+```
+
+**Solutions:**
+1. **Create config directory:**
+   ```bash
+   mkdir -p ~/.config/ttyverse/
+   chmod 700 ~/.config/ttyverse/
+   ```
+
+2. **Check XDG variables:**
+   ```bash
+   echo $XDG_CONFIG_HOME
+   echo $HOME
+   ```
+
+3. **Manual config creation:**
+   ```bash
+   # Create basic config
+   cat > ~/.config/ttyverse/ttyverse_rc << EOF
+   effpause=120
+   verbose=1
+   readline=1
+   EOF
+   ```
+
+### Permission Denied Errors
+
+**Symptoms:**
+```
+-- ERROR: Permission denied writing to config
+```
+
+**Solutions:**
+1. **Fix permissions:**
+   ```bash
+   # Set correct permissions
+   chmod 700 ~/.config/ttyverse/
+   chmod 600 ~/.config/ttyverse/*
+   ```
+
+2. **Check ownership:**
+   ```bash
+   # Verify you own the files
+   ls -la ~/.config/ttyverse/
+   
+   # Fix ownership if needed
+   chown -R $USER:$USER ~/.config/ttyverse/
+   ```
+
+## Getting Debug Information
+
+### Enable Debug Output
+```bash
+# Run with verbose output
+./ttyverse.pl -verbose
+
+# Enable debug in session
+/debug
+/verbose
+```
+
+### Collect System Information
+```bash
+# System info
+uname -a
+perl --version
+curl --version
+
+# TTYverse info
+./ttyverse.pl -version
+
+# Config info
+ls -la ~/.config/ttyverse/
+cat ~/.config/ttyverse/ttyverse_rc | grep -v tokenkey
+```
+
+### Log Analysis
+```bash
+# Check for error patterns
+grep -i error debug.log
+grep -i failed debug.log
+grep -i timeout debug.log
+
+# Timeline of events
+tail -f debug.log
+```
+
+## Reporting Issues
+
+When reporting bugs, include:
+
+1. **TTYverse version:** `./ttyverse.pl -version`
+2. **System info:** `uname -a` and `perl --version`
+3. **Error messages:** Copy exact error text
+4. **Steps to reproduce:** What you were doing when it failed
+5. **Debug output:** Run with `-verbose` and include relevant logs
+6. **Configuration:** Sanitized config (remove tokens!)
+
+**Report at:** https://git.stormux.org/storm/ttyverse/issues
+
+---
+
+**See also:** [FAQ](FAQ) | [Configuration](Configuration) | [Getting Started](Getting-Started)
+
+*Last updated: 2025-07-28*
\ No newline at end of file