LifeRPG_v2.0/docs/USER_GUIDE.md

# LifeRPG User Guide

Welcome to LifeRPG! This guide will help you get started with turning your life into an RPG where you level up by building better habits.

## Table of Contents

1. [Getting Started](#getting-started)
2. [Creating Your First Habit](#creating-your-first-habit)
3. [The Gamification System](#the-gamification-system)
4. [Analytics and Insights](#analytics-and-insights)
5. [Plugin System](#plugin-system)
6. [Advanced Features](#advanced-features)
7. [Troubleshooting](#troubleshooting)

## Getting Started

### Creating Your Account

1. **Navigate to LifeRPG**: Open your web browser and go to `http://localhost:5173`
2. **Register**: Click the "Register" button and fill in your details:
 - Email address
 - Password (minimum 8 characters)
 - Display name (how you'll appear in leaderboards)
3. **Login**: After registration, you'll be automatically logged in

### Dashboard Overview

Your main dashboard contains several sections:

- **Overview Tab**: Summary of your progress, gamification stats, and leaderboard
- **Habits Tab**: Manage your daily habits and routines
- **Analytics Tab**: View detailed charts and insights about your progress
- **Leaderboard Tab**: See how you rank against other users
- **Plugins Tab**: Manage and install plugins to extend functionality
- **Settings Tab**: Configure your preferences and account settings
- **Admin Tab**: (Admin users only) System administration tools

## Creating Your First Habit

### Step 1: Navigate to Habits

Click on the "Habits" tab in your dashboard navigation.

### Step 2: Add a New Habit

1. Click the "Add New Habit" button
2. Fill in the habit details:
 - **Title**: Give your habit a clear, motivating name (e.g., "Morning Exercise")
 - **Description**: Add details about what this habit involves
 - **Category**: Choose from categories like Health, Learning, Productivity, etc.
 - **Target Frequency**: Select how often you want to do this habit:
 - Daily: Every day
 - Weekly: A certain number of times per week
 - Custom: Set your own schedule

### Step 3: Start Tracking

Once created, your habit will appear in your habits list. You can:

- **Complete Today**: Click the checkmark to mark it as done for today
- **View Streak**: See how many consecutive days you've completed it
- **Edit**: Modify the habit details if needed
- **Delete**: Remove the habit (be careful - this can't be undone!)

### Example Habits to Get Started

Here are some simple habits to help you begin:

1. **Drink 8 Glasses of Water** (Health)
2. **Read for 20 Minutes** (Learning)
3. **Write in Journal** (Personal Development)
4. **Take a 10-Minute Walk** (Health)
5. **Practice Gratitude** (Mindfulness)

## The Gamification System

LifeRPG makes habit building fun by turning it into a game!

### Experience Points (XP)

- **Earn XP**: Complete habits to earn experience points
- **Different Values**: Different habits may give different XP amounts
- **Consistency Bonus**: Maintaining streaks can earn bonus XP

### Levels

- **Level Up**: Accumulate XP to advance to higher levels
- **Visual Progress**: See your progress toward the next level
- **Prestige**: Higher levels show your commitment to self-improvement

### Achievements

Unlock achievements by hitting milestones:

- **First Steps**: Create your first habit
- **Streak Master**: Complete a habit 5 days in a row
- **Habit Hero**: Complete 100 habits total
- **Consistency King**: Maintain 3 active streaks
- **Explorer**: Try habits in 5 different categories

### Streaks

- **Daily Streaks**: Track consecutive days of habit completion
- **Motivation**: Streaks provide powerful motivation to maintain consistency
- **Recovery**: Missing a day breaks your streak, but you can always start again

### Leaderboard

- **Global Ranking**: See how you compare to other LifeRPG users
- **Friendly Competition**: Use rankings as motivation, not pressure
- **Privacy**: Only your display name and stats are shown

## Analytics and Insights

### Habit Heatmap

The heatmap shows your daily habit completion patterns:

- **Green Squares**: Days with high completion rates
- **Light Squares**: Days with some completions
- **Empty Squares**: Days with no completions
- **Patterns**: Identify trends and areas for improvement

### Trends and Charts

- **Completion Rate**: Track your overall habit completion percentage over time
- **Category Analysis**: See which categories you're strongest in
- **Weekly/Monthly Views**: Zoom in or out to see different time periods
- **Goal Tracking**: Monitor progress toward personal goals

### Personal Insights

- **Best Days**: Identify which days of the week you're most successful
- **Difficulty Analysis**: See which habits are challenging and which are easy
- **Time Patterns**: Understand your natural rhythms and energy levels

## Plugin System

### What Are Plugins?

Plugins are extensions that add new features to LifeRPG:

- **Custom Widgets**: Add new dashboard components
- **Data Visualizations**: Create unique charts and displays
- **Integrations**: Connect with other apps and services
- **Automation**: Set up automatic actions based on your habits

### Installing Plugins

1. **Navigate to Plugins Tab**: Click "Plugins" in your dashboard
2. **Browse Available**: See plugins that are available for installation
3. **Review Permissions**: Check what access each plugin requests
4. **Install**: Click "Install" and wait for the plugin to load
5. **Configure**: Adjust plugin settings as needed

### Managing Plugins

- **Enable/Disable**: Turn plugins on or off without uninstalling
- **Update**: Keep plugins current with the latest versions
- **Uninstall**: Remove plugins you no longer need
- **Security**: Only install plugins from trusted sources

### Popular Plugin Types

- **Pomodoro Timer**: Time management and focus tracking
- **Habit Reminders**: Custom notification systems
- **Data Exporters**: Backup your data to external services
- **Social Features**: Share progress with friends
- **Mood Tracking**: Monitor emotional patterns alongside habits

## Advanced Features

### Data Export and Backup

- **Regular Backups**: Export your data regularly to avoid loss
- **Format Options**: Download in JSON, CSV, or other formats
- **Privacy**: Your data always remains under your control

### Telemetry and Privacy

- **Opt-in Telemetry**: Choose whether to share anonymous usage data
- **Privacy First**: Personal data is never shared without permission
- **Transparency**: See exactly what data is collected and why

### Integrations

- **Calendar Sync**: Connect with Google Calendar, Outlook
- **Fitness Trackers**: Import data from fitness devices
- **Note Taking**: Link with apps like Notion, Obsidian
- **Social Media**: Share achievements (optional)

### Customization

- **Themes**: Customize the appearance of your dashboard
- **Notifications**: Set up reminders that work for your schedule
- **Goals**: Set personal targets and milestones
- **Categories**: Create custom habit categories

## Tips for Success

### Starting Small

- **Begin with 1-3 habits**: Don't overwhelm yourself
- **Make them easy**: Start with habits you can do in 2-5 minutes
- **Be consistent**: Daily small actions beat occasional big efforts

### Building Momentum

- **Stack habits**: Link new habits to existing routines
- **Use triggers**: Set up environmental cues for your habits
- **Track immediately**: Log completions as soon as you finish

### Staying Motivated

- **Celebrate wins**: Acknowledge every achievement, no matter how small
- **Learn from setbacks**: Missing days is normal - focus on getting back on track
- **Connect with others**: Use the leaderboard for healthy motivation
- **Review regularly**: Check your analytics to see your progress

### Common Pitfalls to Avoid

- **Being too ambitious**: Start small and build up gradually
- **All-or-nothing thinking**: Partial completion is better than none
- **Comparing to others**: Focus on your own journey and progress
- **Perfectionism**: Aim for consistency, not perfection

## Troubleshooting

### Common Issues

#### I Can't Log In

1. **Check your credentials**: Ensure email and password are correct
2. **Password reset**: Use the "Forgot Password" link if available
3. **Clear browser cache**: Try refreshing or clearing your browser data
4. **Check caps lock**: Passwords are case-sensitive

#### My Habits Aren't Saving

1. **Check internet connection**: Ensure you're online
2. **Refresh the page**: Sometimes a simple refresh helps
3. **Try again later**: The server might be temporarily unavailable

#### Plugins Won't Load

1. **Check permissions**: Ensure the plugin has necessary permissions
2. **Disable and re-enable**: Try toggling the plugin off and on
3. **Check for updates**: Make sure you have the latest version
4. **Contact support**: Report persistent plugin issues

#### Data Seems Wrong

1. **Check timezone settings**: Ensure your timezone is set correctly
2. **Verify dates**: Make sure you're looking at the right time period
3. **Refresh analytics**: Some data may take time to update

### Getting Help

#### In-App Help

- **Tooltips**: Hover over UI elements for quick explanations
- **Help Icons**: Look for "?" icons throughout the interface
- **Settings**: Check the settings page for configuration options

#### Community Support

- **GitHub Issues**: Report bugs and request features
- **Community Discord**: Chat with other users and get help
- **Documentation**: Check the full documentation for detailed guides

#### Contacting Support

If you continue to have issues:

1. **Gather information**: Note what you were doing when the problem occurred
2. **Check browser console**: Look for error messages (F12 in most browsers)
3. **Take screenshots**: Visual information helps diagnose problems
4. **Be specific**: Describe exactly what you expected vs. what happened

## Best Practices

### Data Management

- **Regular exports**: Back up your data monthly
- **Review habits**: Remove or modify habits that no longer serve you
- **Clean up**: Archive completed projects and old habits

### Privacy and Security

- **Strong passwords**: Use unique, complex passwords
- **Regular reviews**: Check which plugins have access to your data
- **Logout**: Always log out on shared computers

### Goal Setting

- **SMART goals**: Make goals Specific, Measurable, Achievable, Relevant, Time-bound
- **Regular review**: Adjust goals as your life changes
- **Celebrate milestones**: Acknowledge progress along the way

## What's Next?

### Advanced Features Coming Soon

- **Team challenges**: Compete with friends and family
- **Advanced analytics**: More detailed insights and predictions
- **AI recommendations**: Personalized habit suggestions
- **Mobile app**: Native iOS and Android applications

### Getting Involved

- **Beta testing**: Try new features before they're released
- **Community contributions**: Share your own plugins and templates
- **Feedback**: Help shape the future of LifeRPG

### Continuous Improvement

LifeRPG is constantly evolving. Check back regularly for:

- **New features**: Enhanced functionality and capabilities
- **Plugin updates**: Improved extensions and new options
- **Community content**: User-generated templates and resources

---

## Quick Reference

### Keyboard Shortcuts

- `Ctrl + N`: Create new habit
- `Ctrl + S`: Save current changes
- `Ctrl + D`: Go to dashboard
- `Space`: Mark habit as complete (when focused)

### Common Actions

- **Complete habit**: Click the checkmark next to any habit
- **View analytics**: Click the "Analytics" tab
- **Install plugin**: Go to Plugins tab → Browse → Install
- **Export data**: Settings → Data Export → Download

### Support Resources

- **Documentation**: `/docs` folder in the project
- **API Reference**: `/docs/API_DOCUMENTATION.md`
- **GitHub**: https://git.churchofmalware.org/Diablo_Rain/LifeRPG
- **Issues**: https://git.churchofmalware.org/Diablo_Rain/LifeRPG/issues

Remember: Building better habits is a journey, not a destination. Be patient with yourself, celebrate small wins, and keep moving forward. LifeRPG is here to make that journey more engaging and rewarding!