docs: add comprehensive documentation for DropOut launcher

Co-authored-by: HsiangNianian <44714368+HsiangNianian@users.noreply.github.com>

13 files changed, 3024 insertions, 53 deletions

diff --git a/packages/docs/README.md b/packages/docs/README.md
index 2b4c09a..055e479 100644
--- a/packages/docs/README.md
+++ b/packages/docs/README.md
@@ -1,14 +1,157 @@
-# docs
+# DropOut Documentation
 
-This is a React Router application generated with
-[Create Fumadocs](https://github.com/fuma-nama/fumadocs).
+This is the official documentation site for DropOut Minecraft Launcher, built with [Fumadocs](https://fumadocs.dev) and React Router v7.
 
-Run development server:
+## Overview
+
+The documentation covers:
+- **Getting Started**: Installation and first-time setup
+- **Features**: Detailed guides for all launcher features
+- **Architecture**: Technical design and implementation details
+- **Development**: Building and contributing to DropOut
+- **Troubleshooting**: Common issues and solutions
+
+## Development
+
+### Prerequisites
+
+- Node.js 22+
+- pnpm 9+
+
+### Setup
+
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+### Run Development Server
 
 ```bash
-npm run dev
-# or
 pnpm dev
-# or
-yarn dev
 ```
+
+This starts the development server at `http://localhost:5173` with hot reload enabled.
+
+### Build for Production
+
+```bash
+pnpm build
+```
+
+The production build will be output to the `build/` directory.
+
+### Type Checking
+
+```bash
+pnpm types:check
+```
+
+### Linting and Formatting
+
+```bash
+# Check code
+pnpm lint
+
+# Format code
+pnpm format
+```
+
+## Project Structure
+
+```
+packages/docs/
+├── content/
+│   └── docs/              # Documentation content (MDX)
+│       ├── index.mdx      # Home page
+│       ├── getting-started.mdx
+│       ├── architecture.mdx
+│       ├── development.mdx
+│       ├── troubleshooting.mdx
+│       └── features/      # Feature-specific docs
+├── app/                   # React Router app
+├── public/                # Static assets
+├── source.config.ts       # Fumadocs configuration
+└── react-router.config.ts # React Router configuration
+```
+
+## Writing Documentation
+
+### MDX Format
+
+All documentation is written in MDX (Markdown with JSX):
+
+```mdx
+---
+title: Page Title
+description: Page description for SEO
+---
+
+# Page Title
+
+Content goes here...
+
+<Cards>
+  <Card title="Link Title" href="/path" />
+</Cards>
+```
+
+### Available Components
+
+Fumadocs provides several components:
+
+- `<Card>` - Link cards
+- `<Cards>` - Card container
+- `<Callout>` - Info/warning boxes
+- `<Tabs>` - Tabbed content
+- `<Steps>` - Numbered steps
+- Code blocks with syntax highlighting
+
+### Adding New Pages
+
+1. Create new `.mdx` file in `content/docs/`
+2. Add frontmatter with title and description
+3. Write content using MDX
+4. Update `meta.json` to include the page
+5. Test locally with `pnpm dev`
+
+### Organizing Content
+
+Use `meta.json` files to organize navigation:
+
+```json
+{
+  "title": "Section Title",
+  "pages": [
+    "page1",
+    "page2",
+    {
+      "title": "Subsection",
+      "pages": ["sub1", "sub2"]
+    }
+  ]
+}
+```
+
+## Deployment
+
+The documentation is automatically deployed when changes are merged to the main branch.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test locally
+5. Submit a pull request
+
+## Links
+
+- [DropOut Repository](https://github.com/HydroRoll-Team/DropOut)
+- [Fumadocs](https://fumadocs.dev)
+- [React Router](https://reactrouter.com)
+
+## License
+
+MIT License - see the main repository for details.
diff --git a/packages/docs/content/docs/architecture.mdx b/packages/docs/content/docs/architecture.mdx
new file mode 100644
index 0000000..f8cc8f4
--- /dev/null
+++ b/packages/docs/content/docs/architecture.mdx
@@ -0,0 +1,282 @@
+---
+title: Architecture
+description: Technical architecture and design of DropOut Minecraft Launcher
+---
+
+# Architecture
+
+DropOut is built with a modern tech stack designed for performance, security, and cross-platform compatibility.
+
+## Technology Stack
+
+### Backend (Rust)
+- **Framework**: Tauri v2
+- **Language**: Rust (Edition 2021)
+- **Async Runtime**: Tokio
+- **HTTP Client**: reqwest with native-tls
+
+### Frontend (Svelte)
+- **Framework**: Svelte 5 (with runes)
+- **Styling**: Tailwind CSS 4
+- **Build Tool**: Vite with Rolldown
+- **Package Manager**: pnpm
+
+### Documentation
+- **Framework**: Fumadocs with React Router v7
+- **Content**: MDX files
+- **Styling**: Tailwind CSS 4
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Frontend (Svelte 5)                   │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
+│  │  Stores  │  │Components│  │ UI Views │  │Particles│ │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬────┘ │
+│       │             │             │              │      │
+│       └─────────────┴─────────────┴──────────────┘      │
+│                          │                              │
+│                   Tauri Commands                        │
+│                    Events/Emitters                      │
+└──────────────────────────┬──────────────────────────────┘
+                           │
+┌──────────────────────────┴──────────────────────────────┐
+│                  Backend (Rust/Tauri)                    │
+│  ┌─────────────────────────────────────────────────┐    │
+│  │               main.rs (Commands)                 │    │
+│  └──────────────┬──────────────────────────────────┘    │
+│                 │                                        │
+│  ┌──────────────┴───────────────────────────────┐       │
+│  │               Core Modules                   │       │
+│  │  ┌──────┐ ┌────────┐ ┌──────┐ ┌──────────┐  │       │
+│  │  │ Auth │ │Download│ │ Java │ │ Instance │  │       │
+│  │  └──────┘ └────────┘ └──────┘ └──────────┘  │       │
+│  │  ┌──────┐ ┌────────┐ ┌──────┐ ┌──────────┐  │       │
+│  │  │Fabric│ │ Forge  │ │Config│ │Manifest  │  │       │
+│  │  └──────┘ └────────┘ └──────┘ └──────────┘  │       │
+│  └──────────────────────────────────────────────┘       │
+│                                                          │
+│  ┌─────────────────────────────────────────────────┐    │
+│  │                Utils & Helpers                   │    │
+│  │  • ZIP extraction  • Path utilities             │    │
+│  └─────────────────────────────────────────────────┘    │
+└──────────────────────────┬──────────────────────────────┘
+                           │
+                    External APIs
+                           │
+        ┌──────────────────┼──────────────────┐
+        │                  │                  │
+  ┌─────┴────┐      ┌──────┴─────┐    ┌──────┴─────┐
+  │  Mojang  │      │   Fabric   │    │   Forge    │
+  │   APIs   │      │    Meta    │    │   Maven    │
+  └──────────┘      └────────────┘    └────────────┘
+```
+
+## Core Components
+
+### Frontend State Management
+
+DropOut uses **Svelte 5 runes** for reactive state management:
+
+```typescript
+// stores/auth.svelte.ts
+export class AuthState {
+  currentAccount = $state<Account | null>(null);  // Reactive
+  isLoginModalOpen = $state(false);
+  
+  $effect(() => {  // Side effects
+    // Auto-runs when dependencies change
+  });
+}
+```
+
+**Key Stores:**
+- `auth.svelte.ts`: Authentication state and login flow
+- `settings.svelte.ts`: Launcher settings and Java detection
+- `game.svelte.ts`: Game running state and logs
+- `instances.svelte.ts`: Instance management
+- `ui.svelte.ts`: UI state (toasts, modals, active view)
+
+### Backend Architecture
+
+#### Command Pattern
+All Tauri commands follow this structure:
+
+```rust
+#[tauri::command]
+async fn command_name(
+    window: Window,
+    state: State<'_, SomeState>,
+    param: Type,
+) -> Result<ReturnType, String> {
+    emit_log!(window, "Status message");
+    // Async logic
+    Ok(result)
+}
+```
+
+#### Event Communication
+
+**Rust → Frontend (Progress Updates):**
+```rust
+window.emit("launcher-log", "Downloading...")?;
+window.emit("download-progress", progress_struct)?;
+```
+
+**Frontend → Rust (Commands):**
+```typescript
+import { invoke } from "@tauri-apps/api/core";
+const result = await invoke("start_game", { versionId: "1.20.4" });
+```
+
+### Core Modules
+
+#### Authentication (`core/auth.rs`)
+- **Microsoft OAuth 2.0**: Device Code Flow
+- **Offline Authentication**: Local UUID generation
+- **Token Management**: Refresh token storage and auto-refresh
+- **Xbox Live Integration**: Full authentication chain
+
+**Authentication Flow:**
+1. Device Code Request → MS Token
+2. Xbox Live Authentication
+3. XSTS Authorization
+4. Minecraft Token Exchange
+5. Profile Fetching
+
+#### Downloader (`core/downloader.rs`)
+- **Concurrent Downloads**: Configurable thread pool
+- **Resume Support**: `.part` and `.part.meta` files
+- **Multi-segment Downloads**: Large files split into chunks
+- **Checksum Verification**: SHA1/SHA256 validation
+- **Progress Tracking**: Real-time events to frontend
+
+#### Java Management (`core/java.rs`)
+- **Auto-detection**: Scans system paths
+- **Adoptium Integration**: Download JDK/JRE on-demand
+- **Catalog Caching**: 24-hour cache for version lists
+- **Installation**: Extracts to app data directory
+- **Cancellation**: Atomic flag for download cancellation
+
+#### Fabric Support (`core/fabric.rs`)
+- **Meta API Integration**: Fetch loader versions
+- **Profile Generation**: Creates version JSON
+- **Library Resolution**: Maven artifact handling
+
+#### Forge Support (`core/forge.rs`)
+- **Installer Execution**: Runs Forge installer
+- **Profile Parsing**: Extracts install profile
+- **Library Management**: Handles Forge-specific libraries
+
+#### Instance System (`core/instance.rs`)
+- **Isolation**: Separate directories per instance
+- **Configuration**: Per-instance settings
+- **Mod Management**: Instance-specific mods
+- **Version Locking**: Reproducible environments
+
+#### Version Management
+- **Manifest Parsing** (`manifest.rs`): Mojang version manifest
+- **Inheritance System** (`version_merge.rs`): Parent version merging
+- **Game Version** (`game_version.rs`): JSON parsing and validation
+- **Rules Engine** (`rules.rs`): OS/feature conditional logic
+
+### File Structure
+
+```
+~/.local/share/com.dropout.launcher/  (Linux)
+~/Library/Application Support/com.dropout.launcher/  (macOS)
+%APPDATA%/com.dropout.launcher/  (Windows)
+├── versions/
+│   └── <version_id>/
+│       ├── <version_id>.json
+│       ├── <version_id>.jar
+│       └── natives/
+├── libraries/
+│   └── <maven-path>/
+├── assets/
+│   ├── indexes/
+│   └── objects/
+├── instances/
+│   └── <instance_name>/
+│       ├── mods/
+│       ├── config/
+│       └── saves/
+├── java/
+│   └── <version>/
+├── config.json
+└── accounts.json
+```
+
+## Data Flow
+
+### Game Launch Sequence
+
+1. **Frontend**: User clicks "Launch Game"
+2. **Command**: `start_game(version_id)` invoked
+3. **Backend Processing**:
+   - Load version JSON (with inheritance)
+   - Resolve all libraries
+   - Download missing assets
+   - Extract native libraries
+   - Build classpath
+   - Construct JVM arguments
+   - Replace placeholders
+4. **Process Spawn**: Launch Java with arguments
+5. **Stream Logs**: Emit stdout/stderr to frontend
+6. **Monitor**: Track game process status
+
+### Download Flow
+
+1. **Queue Creation**: List of files to download
+2. **Concurrent Processing**: Semaphore-limited threads
+3. **Resume Check**: Verify existing `.part` files
+4. **Download**: Multi-segment for large files
+5. **Verification**: Checksum validation
+6. **Progress Events**: Real-time updates to UI
+7. **Completion**: Move from `.part` to final location
+
+### Authentication Flow
+
+1. **Device Code Request**: Get user code + device code
+2. **User Authorization**: User visits URL and enters code
+3. **Token Polling**: Frontend polls for completion
+4. **Token Exchange**: MS token → Xbox → XSTS → Minecraft
+5. **Profile Fetch**: Get username and UUID
+6. **Storage**: Save account with refresh token
+7. **Auto-refresh**: Background token refresh on expiry
+
+## Platform-Specific Considerations
+
+### Linux
+- Uses GTK WebView (`webkit2gtk`)
+- System Java detection from `/usr/lib/jvm`
+- Desktop file integration
+
+### macOS
+- Uses system WebKit
+- App bundle structure
+- Keychain integration for secure storage
+
+### Windows
+- Uses WebView2 runtime
+- Registry Java detection
+- MSI installer support
+- No console window in release builds
+
+## Performance Optimizations
+
+- **Concurrent Downloads**: Parallel asset/library downloads
+- **Lazy Loading**: Load version manifests on-demand
+- **Caching**: Java catalog, version manifests
+- **Native Code**: Rust for CPU-intensive operations
+- **Async I/O**: Tokio for non-blocking operations
+
+## Security Features
+
+- **Token Encryption**: Secure storage of auth tokens
+- **HTTPS Only**: All external API calls
+- **Checksum Validation**: File integrity verification
+- **Sandboxed Execution**: Tauri security model
+- **No Arbitrary Code**: No eval or dynamic code execution
+
diff --git a/packages/docs/content/docs/development.mdx b/packages/docs/content/docs/development.mdx
new file mode 100644
index 0000000..f7beabb
--- /dev/null
+++ b/packages/docs/content/docs/development.mdx
@@ -0,0 +1,547 @@
+---
+title: Development Guide
+description: Build, test, and contribute to DropOut
+---
+
+# Development Guide
+
+This guide will help you set up a development environment, build DropOut from source, and contribute to the project.
+
+## Prerequisites
+
+### Required Software
+
+1. **Rust** (latest stable)
+   ```bash
+   # Install via rustup
+   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+   ```
+
+2. **Node.js** (v22+) and **pnpm** (v9+)
+   ```bash
+   # Install Node.js from https://nodejs.org/
+   # Install pnpm
+   npm install -g pnpm@9
+   ```
+
+3. **System Dependencies**
+
+   Follow the [Tauri Prerequisites](https://v2.tauri.app/start/prerequisites/) for your platform:
+
+   **Linux (Debian/Ubuntu):**
+   ```bash
+   sudo apt update
+   sudo apt install libwebkit2gtk-4.1-dev \
+     build-essential \
+     curl \
+     wget \
+     file \
+     libssl-dev \
+     libayatana-appindicator3-dev \
+     librsvg2-dev
+   ```
+
+   **macOS:**
+   ```bash
+   xcode-select --install
+   ```
+
+   **Windows:**
+   - Install [Microsoft Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
+   - Install [WebView2](https://developer.microsoft.com/microsoft-edge/webview2/)
+
+## Getting Started
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/HydroRoll-Team/DropOut.git
+cd DropOut
+```
+
+### Install Dependencies
+
+**Frontend dependencies:**
+```bash
+cd packages/ui
+pnpm install
+cd ../..
+```
+
+**Documentation dependencies:**
+```bash
+cd packages/docs
+pnpm install
+cd ../..
+```
+
+### Development Mode
+
+Run DropOut in development mode with hot reload:
+
+```bash
+cargo tauri dev
+```
+
+This will:
+1. Start the frontend dev server (Vite on port 5173)
+2. Compile the Rust backend
+3. Open the Tauri window
+4. Enable hot reload for frontend changes
+5. Recompile on Rust file changes
+
+**Terminal output:**
+- Frontend logs from Vite
+- Rust stdout/stderr
+- Compilation status
+
+### Building for Production
+
+Build release binaries:
+
+```bash
+cargo tauri build
+```
+
+**Output locations:**
+- **Linux**: `src-tauri/target/release/bundle/`
+  - `.deb` package
+  - `.AppImage` bundle
+- **macOS**: `src-tauri/target/release/bundle/`
+  - `.dmg` installer
+  - `.app` bundle
+- **Windows**: `src-tauri/target/release/bundle/`
+  - `.msi` installer
+  - `.exe` executable
+
+## Project Structure
+
+```
+DropOut/
+├── src-tauri/              # Rust backend
+│   ├── src/
+│   │   ├── main.rs         # Tauri commands & entry point
+│   │   ├── core/           # Core modules
+│   │   │   ├── auth.rs     # Authentication
+│   │   │   ├── downloader.rs # Download manager
+│   │   │   ├── fabric.rs   # Fabric support
+│   │   │   ├── forge.rs    # Forge support
+│   │   │   ├── java.rs     # Java management
+│   │   │   ├── instance.rs # Instance system
+│   │   │   └── ...
+│   │   └── utils/          # Utilities
+│   └── Cargo.toml
+├── packages/
+│   ├── ui/                 # Svelte 5 frontend
+│   │   ├── src/
+│   │   │   ├── App.svelte
+│   │   │   ├── components/
+│   │   │   ├── stores/     # State management
+│   │   │   └── lib/
+│   │   └── package.json
+│   └── docs/               # Documentation site
+│       ├── content/docs/
+│       └── package.json
+├── .github/
+│   └── workflows/          # CI/CD pipelines
+└── scripts/                # Build scripts
+```
+
+## Development Workflows
+
+### Frontend Development
+
+**Start dev server:**
+```bash
+cd packages/ui
+pnpm dev
+```
+
+**Type checking:**
+```bash
+pnpm check
+```
+
+**Linting:**
+```bash
+pnpm lint
+```
+
+**Formatting:**
+```bash
+pnpm format
+```
+
+### Backend Development
+
+**Run Rust tests:**
+```bash
+cargo test
+```
+
+**Check code:**
+```bash
+cargo check
+```
+
+**Format code:**
+```bash
+cargo fmt
+```
+
+**Lint code:**
+```bash
+cargo clippy
+```
+
+### Documentation Development
+
+**Start docs dev server:**
+```bash
+cd packages/docs
+pnpm dev
+```
+
+**Build docs:**
+```bash
+pnpm build
+```
+
+**Type check:**
+```bash
+pnpm types:check
+```
+
+## Code Style
+
+### Rust
+
+Follow standard Rust conventions:
+- Use `cargo fmt` for formatting
+- Use `cargo clippy` for linting
+- Write documentation comments (`///`)
+- Handle errors properly
+- Use async/await for I/O
+
+**Example:**
+```rust
+/// Starts the Microsoft authentication device flow
+#[tauri::command]
+async fn start_microsoft_login(
+    window: Window,
+) -> Result<DeviceCodeResponse, String> {
+    emit_log!(window, "Starting Microsoft login...");
+    
+    start_device_flow()
+        .await
+        .map_err(|e| e.to_string())
+}
+```
+
+### TypeScript/Svelte
+
+Follow the project's conventions:
+- Use Svelte 5 runes (`$state`, `$effect`)
+- Prefer TypeScript over JavaScript
+- Use Biome for formatting and linting
+- Follow component structure
+
+**Example:**
+```typescript
+// stores/auth.svelte.ts
+export class AuthState {
+  currentAccount = $state<Account | null>(null);
+  isLoginModalOpen = $state(false);
+  
+  async login(username: string) {
+    const account = await invoke('offline_login', { username });
+    this.currentAccount = account;
+  }
+}
+```
+
+## Testing
+
+### Unit Tests
+
+**Rust:**
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_generate_offline_uuid() {
+        let uuid = generate_offline_uuid("Player");
+        assert!(uuid.len() > 0);
+    }
+}
+```
+
+**Run:**
+```bash
+cargo test
+```
+
+### Integration Tests
+
+Test the full application:
+1. Build in dev mode: `cargo tauri dev`
+2. Manually test features
+3. Check console for errors
+4. Verify UI behavior
+
+### CI Tests
+
+GitHub Actions runs tests on:
+- Ubuntu (latest)
+- Arch Linux (Wayland)
+- Windows (latest)
+- macOS (ARM64)
+
+View workflow: `.github/workflows/test.yml`
+
+## Debugging
+
+### Frontend Debugging
+
+1. Open DevTools in Tauri window: `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Option+I` (macOS)
+2. Check Console for errors
+3. Use React DevTools or Svelte DevTools
+4. Monitor Network tab for API calls
+
+### Backend Debugging
+
+**Print debugging:**
+```rust
+emit_log!(window, format!("Debug: {}", value));
+println!("Debug: {}", value);
+```
+
+**Rust debugger:**
+```bash
+# Install rust-lldb or rust-gdb
+cargo install rust-gdb
+
+# Debug
+rust-gdb target/debug/dropout
+```
+
+### Logging
+
+**Frontend:**
+```typescript
+console.log("Info message");
+console.error("Error message");
+```
+
+**Backend:**
+```rust
+emit_log!(window, "Status update");
+eprintln!("Error: {}", error);
+```
+
+## Contributing
+
+### Contribution Workflow
+
+1. **Fork** the repository
+2. **Create** a feature branch:
+   ```bash
+   git checkout -b feature/my-feature
+   ```
+3. **Make** your changes
+4. **Test** thoroughly
+5. **Commit** with conventional commits:
+   ```bash
+   git commit -m "feat: add new feature"
+   ```
+6. **Push** to your fork:
+   ```bash
+   git push origin feature/my-feature
+   ```
+7. **Create** a pull request
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+**Format:**
+```
+<type>[scope]: <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation
+- `style`: Formatting
+- `refactor`: Code restructuring
+- `perf`: Performance improvement
+- `test`: Adding tests
+- `chore`: Maintenance
+
+**Examples:**
+```bash
+feat(auth): add offline authentication support
+fix(java): resolve detection on Windows
+docs: update installation guide
+refactor(download): simplify progress tracking
+```
+
+### Pull Request Guidelines
+
+**Before submitting:**
+- [ ] Code follows style guidelines
+- [ ] Tests pass locally
+- [ ] Documentation updated if needed
+- [ ] No unnecessary files committed
+- [ ] Commit messages are clear
+
+**PR Description:**
+- Explain what and why
+- Link related issues
+- List breaking changes
+- Add screenshots for UI changes
+
+### Code Review
+
+Maintainers will review your PR for:
+- Code quality and style
+- Test coverage
+- Documentation
+- Performance impact
+- Security implications
+
+Be responsive to feedback and make requested changes.
+
+## Common Tasks
+
+### Adding a Tauri Command
+
+1. **Define command in `main.rs`:**
+   ```rust
+   #[tauri::command]
+   async fn my_command(param: String) -> Result<String, String> {
+       Ok(format!("Received: {}", param))
+   }
+   ```
+
+2. **Register in builder:**
+   ```rust
+   .invoke_handler(tauri::generate_handler![
+       my_command,
+       // ... other commands
+   ])
+   ```
+
+3. **Call from frontend:**
+   ```typescript
+   const result = await invoke('my_command', { param: 'value' });
+   ```
+
+### Adding a UI Component
+
+1. **Create component file:**
+   ```svelte
+   <!-- packages/ui/src/components/MyComponent.svelte -->
+   <script lang="ts">
+     let count = $state(0);
+   </script>
+
+   <button onclick={() => count++}>
+     Count: {count}
+   </button>
+   ```
+
+2. **Import and use:**
+   ```svelte
+   <script>
+     import MyComponent from './components/MyComponent.svelte';
+   </script>
+
+   <MyComponent />
+   ```
+
+### Adding a Store
+
+1. **Create store file:**
+   ```typescript
+   // packages/ui/src/stores/mystore.svelte.ts
+   export class MyState {
+     value = $state(0);
+     
+     increment() {
+       this.value++;
+     }
+   }
+   
+   export const myState = new MyState();
+   ```
+
+2. **Use in components:**
+   ```svelte
+   <script>
+     import { myState } from '../stores/mystore.svelte';
+   </script>
+
+   <button onclick={() => myState.increment()}>
+     {myState.value}
+   </button>
+   ```
+
+## Troubleshooting Development Issues
+
+### Build Failures
+
+**"cannot find -lwebkit2gtk"**
+```bash
+# Install WebKit dependencies
+sudo apt install libwebkit2gtk-4.1-dev
+```
+
+**"pnpm not found"**
+```bash
+# Install pnpm
+npm install -g pnpm@9
+```
+
+**"Rust version too old"**
+```bash
+# Update Rust
+rustup update
+```
+
+### Runtime Issues
+
+**"Failed to load dynamic library"**
+- Rebuild: `cargo clean && cargo tauri dev`
+- Check library paths
+- Verify dependencies installed
+
+**"CORS error"**
+- Normal in dev mode
+- Tauri handles CORS automatically
+
+**"Hot reload not working"**
+- Check Vite config
+- Restart dev server
+- Clear browser cache
+
+## Resources
+
+- [Tauri Documentation](https://v2.tauri.app/)
+- [Svelte 5 Documentation](https://svelte.dev/docs)
+- [Rust Book](https://doc.rust-lang.org/book/)
+- [DropOut Repository](https://github.com/HydroRoll-Team/DropOut)
+
+## Getting Help
+
+- **Issues**: [GitHub Issues](https://github.com/HydroRoll-Team/DropOut/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/HydroRoll-Team/DropOut/discussions)
+- **Documentation**: This site
+
diff --git a/packages/docs/content/docs/features/authentication.mdx b/packages/docs/content/docs/features/authentication.mdx
new file mode 100644
index 0000000..67e3c19
--- /dev/null
+++ b/packages/docs/content/docs/features/authentication.mdx
@@ -0,0 +1,267 @@
+---
+title: Authentication
+description: Microsoft OAuth and offline authentication in DropOut
+---
+
+# Authentication
+
+DropOut supports two authentication methods: Microsoft Account (for official Minecraft) and Offline Mode (for testing and offline play).
+
+## Microsoft Authentication
+
+### Overview
+
+DropOut uses the **Device Code Flow** for Microsoft authentication, which:
+- Doesn't require a redirect URL (no browser integration)
+- Works on any device with a browser
+- Provides a simple code-based authentication
+- Fully compliant with Microsoft OAuth 2.0
+
+### Authentication Process
+
+The authentication chain consists of multiple steps:
+
+1. **Device Code** → User authorization
+2. **MS Token** → Access + refresh tokens
+3. **Xbox Live** → Xbox token + UHS
+4. **XSTS** → Security token
+5. **Minecraft** → Game access token
+6. **Profile** → Username + UUID
+
+#### Step 1: Device Code Request
+1. Click "Login with Microsoft"
+2. DropOut requests a device code from Microsoft
+3. You receive:
+   - User code (e.g., `A1B2-C3D4`)
+   - Verification URL (usually `https://microsoft.com/link`)
+   - Device code (used internally)
+
+#### Step 2: User Authorization
+1. Visit the verification URL in any browser
+2. Enter the user code
+3. Sign in with your Microsoft account
+4. Authorize DropOut to access your Minecraft profile
+
+#### Step 3: Token Exchange
+- DropOut polls Microsoft for authorization completion
+- Once authorized, receives an access token and refresh token
+- Refresh token is stored for future logins
+
+#### Step 4: Xbox Live Authentication
+- Microsoft token is exchanged for Xbox Live token
+- Retrieves User Hash (UHS) for next step
+
+#### Step 5: XSTS Authorization
+- Xbox Live token is used to get XSTS token
+- This token is specific to Minecraft services
+
+#### Step 6: Minecraft Login
+- XSTS token is exchanged for Minecraft access token
+- Uses endpoint: `/launcher/login`
+
+#### Step 7: Profile Fetching
+- Retrieves your Minecraft username
+- Fetches your UUID
+- Checks if you own Minecraft
+
+### Token Management
+
+**Access Token:**
+- Short-lived (typically 1 hour)
+- Used for game authentication
+- Automatically refreshed when expired
+
+**Refresh Token:**
+- Long-lived (typically 90 days)
+- Stored securely in `accounts.json`
+- Used to obtain new access tokens
+
+**Auto-refresh:**
+```rust
+// Automatic refresh when token expires
+if account.expires_at < current_time {
+    refresh_full_auth(&account).await?;
+}
+```
+
+### Security Considerations
+
+- Tokens are stored in platform-specific app data directory
+- HTTPS only for all API calls
+- No credentials stored (only tokens)
+- User-Agent header required (bypasses MS WAF)
+
+### Troubleshooting Microsoft Login
+
+**"Device code expired"**
+- Codes expire after 15 minutes
+- Start the login process again
+
+**"Authorization pending"**
+- Normal during the waiting phase
+- Complete authorization in the browser
+
+**"Invalid token"**
+- Token may have expired
+- Log out and log back in
+
+**"You don't own Minecraft"**
+- Verify your Microsoft account owns Minecraft Java Edition
+- Check at https://www.minecraft.net/profile
+
+## Offline Authentication
+
+### Overview
+
+Offline mode creates a local account that doesn't require internet connectivity or a Microsoft account. This is useful for:
+- Testing and development
+- Playing without internet
+- LAN multiplayer
+- Mod development
+
+### Creating an Offline Account
+
+1. Click "Offline Mode" in the login screen
+2. Enter a username (3-16 characters)
+3. Click "Create Account"
+
+### How It Works
+
+**UUID Generation:**
+```rust
+// Deterministic UUID v3 from username
+let uuid = generate_offline_uuid(&username);
+```
+
+- Uses UUID v3 (namespace-based)
+- Deterministic: same username = same UUID
+- No network requests
+
+**Authentication:**
+- Returns `"null"` as access token
+- Minecraft accepts null token in offline mode
+- Username and UUID stored locally
+
+### Limitations
+
+- Cannot join online servers
+- No skin support
+- No cape support
+- No Microsoft account features
+
+### Use Cases
+
+**Development:**
+```bash
+# Testing mod development
+cargo tauri dev
+# Use offline mode to test quickly
+```
+
+**LAN Play:**
+- Join LAN worlds without authentication
+- Host LAN worlds
+
+**Offline Play:**
+- Singleplayer without internet
+- No authentication required
+
+## Account Management
+
+### Switching Accounts
+
+Currently, DropOut supports one active account at a time. Multi-account support is planned.
+
+**To switch accounts:**
+1. Log out of current account
+2. Log in with new account
+
+### Account Storage
+
+Accounts are stored in `accounts.json`:
+
+```json
+{
+  "current_account_id": "uuid-here",
+  "accounts": [
+    {
+      "id": "uuid",
+      "type": "Microsoft",
+      "username": "PlayerName",
+      "access_token": "...",
+      "refresh_token": "...",
+      "expires_at": 1234567890
+    }
+  ]
+}
+```
+
+### Deleting Accounts
+
+To remove an account:
+1. Open Settings
+2. Navigate to Accounts
+3. Click "Log Out"
+4. Or manually delete `accounts.json`
+
+## API Reference
+
+### Tauri Commands
+
+**Start Microsoft Login:**
+```typescript
+const { user_code, verification_uri } = await invoke('start_microsoft_login');
+```
+
+**Complete Microsoft Login:**
+```typescript
+const account = await invoke('complete_microsoft_login', { deviceCode });
+```
+
+**Offline Login:**
+```typescript
+const account = await invoke('offline_login', { username: 'Player' });
+```
+
+**Logout:**
+```typescript
+await invoke('logout');
+```
+
+**Get Current Account:**
+```typescript
+const account = await invoke('get_current_account');
+```
+
+### Events
+
+**Authentication Status:**
+```typescript
+listen('auth-status', (event) => {
+  console.log(event.payload); // "logged_in" | "logged_out"
+});
+```
+
+## Best Practices
+
+### For Players
+
+1. **Use Microsoft Account** for official servers
+2. **Keep tokens secure** - don't share accounts.json
+3. **Refresh tokens regularly** by logging in
+4. **Use offline mode** only for testing
+
+### For Developers
+
+1. **Handle token expiration** gracefully
+2. **Implement retry logic** for network failures
+3. **Cache account data** to reduce API calls
+4. **Validate tokens** before game launch
+
+## Future Enhancements
+
+- **Multi-account support**: Switch between accounts easily
+- **Account profiles**: Save per-account settings
+- **Auto-login**: Remember last account
+- **Token encryption**: Enhanced security for stored tokens
+
diff --git a/packages/docs/content/docs/features/index.mdx b/packages/docs/content/docs/features/index.mdx
new file mode 100644
index 0000000..b36bb61
--- /dev/null
+++ b/packages/docs/content/docs/features/index.mdx
@@ -0,0 +1,177 @@
+---
+title: Features Overview
+description: Comprehensive guide to all DropOut features
+---
+
+# Features Overview
+
+DropOut is packed with features designed for both casual players and power users. This guide covers all major capabilities.
+
+## Core Features
+
+<Cards>
+  <Card 
+    title="Authentication" 
+    href="/docs/features/authentication"
+    description="Microsoft OAuth and offline authentication"
+  />
+  <Card 
+    title="Java Management" 
+    href="/docs/features/java"
+    description="Auto-detection and installation of Java runtimes"
+  />
+  <Card 
+    title="Mod Loaders" 
+    href="/docs/features/mod-loaders"
+    description="Fabric and Forge support with easy installation"
+  />
+  <Card 
+    title="Instances" 
+    href="/docs/features/instances"
+    description="Isolated game environments with independent configs"
+  />
+  <Card 
+    title="Downloads" 
+    href="/docs/features/downloads"
+    description="Fast concurrent downloads with resume support"
+  />
+  <Card 
+    title="AI Assistant" 
+    href="/docs/features/assistant"
+    description="Built-in AI helper for troubleshooting and guidance"
+  />
+</Cards>
+
+## Quick Feature Matrix
+
+| Feature | Status | Description |
+|---------|--------|-------------|
+| Microsoft Authentication | ✅ Complete | OAuth 2.0 with device code flow |
+| Offline Authentication | ✅ Complete | Local accounts for offline play |
+| Token Auto-refresh | ✅ Complete | Automatic refresh of expired tokens |
+| Java Auto-detection | ✅ Complete | Scans system for Java installations |
+| Java Download | ✅ Complete | Download Adoptium JDK/JRE versions |
+| Fabric Support | ✅ Complete | Install and launch Fabric loader |
+| Forge Support | ✅ Complete | Install and launch Forge loader |
+| Instance System | ✅ Complete | Isolated game environments |
+| GitHub Integration | ✅ Complete | View releases and changelogs |
+| Concurrent Downloads | ✅ Complete | Multi-threaded asset downloads |
+| Resume Downloads | ✅ Complete | Resume interrupted downloads |
+| AI Assistant | ✅ Complete | Built-in troubleshooting helper |
+| Config Editor | ✅ Complete | JSON/TOML configuration editor |
+| Custom Resolution | ✅ Complete | Set game window dimensions |
+| Memory Allocation | ✅ Complete | Customize JVM memory settings |
+| Multi-account | 🚧 In Progress | Switch between multiple accounts |
+| Mods Manager | 🚧 Planned | Enable/disable mods in launcher |
+| Launcher Auto-update | 🚧 Planned | Self-updating mechanism |
+| Custom Game Directory | 🚧 Planned | Choose game files location |
+| Import Profiles | 🚧 Planned | Import from MultiMC/Prism |
+
+## Performance Features
+
+### Concurrent Downloads
+- Configurable thread count (default: 10)
+- Parallel asset and library downloads
+- Progress tracking per file
+- ETA calculation
+
+### Resume Support
+- Interrupted downloads auto-resume
+- `.part` files track progress
+- Multi-segment downloads for large files
+- Metadata files for state tracking
+
+### Caching
+- Java catalog cached for 24 hours
+- Version manifests cached locally
+- Asset index caching
+- Library deduplication
+
+## User Interface Features
+
+### Modern Design
+- Dark mode enforced for eye comfort
+- Particle background effects
+- Clean, distraction-free layout
+- Responsive design
+
+### Real-time Feedback
+- Live download progress
+- Game console output
+- Log streaming
+- Toast notifications
+
+### Settings Management
+- Memory allocation slider
+- Resolution customization
+- Java path selection
+- Thread count configuration
+- Custom JVM arguments
+
+## Advanced Features
+
+### Version Inheritance
+Modded versions (Fabric/Forge) automatically inherit from parent vanilla versions:
+- Libraries merged from parent + mod loader
+- Arguments combined and deduplicated
+- Assets inherited from vanilla version
+
+### Native Library Extraction
+- Platform-specific native extraction
+- Automatic cleanup
+- Proper library path configuration
+
+### Rules Engine
+- OS-specific library filtering
+- Feature flag support
+- Architecture detection
+
+### Download Queue Persistence
+- Save incomplete downloads
+- Resume after launcher restart
+- Queue priority management
+
+## Developer Features
+
+### Config Editor
+Built-in JSON/TOML editor with:
+- Syntax highlighting
+- Validation
+- Quick access to all configs
+
+### Log Access
+- Real-time game logs
+- Launcher debug logs
+- Copy/export functionality
+
+### AI Assistant
+- Troubleshooting guidance
+- Error analysis
+- Configuration help
+- Documentation search
+
+## Coming Soon
+
+### Multi-account Management
+- Switch between accounts easily
+- Account profiles
+- Quick switching
+
+### Mods Manager
+- Browse and install mods
+- Enable/disable mods
+- Mod compatibility checking
+- Version management
+
+### Profile Import
+- Import from MultiMC
+- Import from Prism Launcher
+- Import from other launchers
+- Preserve settings and saves
+
+### Launcher Auto-update
+- Background update checks
+- One-click updates
+- Version history
+- Rollback support
+
diff --git a/packages/docs/content/docs/features/java.mdx b/packages/docs/content/docs/features/java.mdx
new file mode 100644
index 0000000..1afdab7
--- /dev/null
+++ b/packages/docs/content/docs/features/java.mdx
@@ -0,0 +1,395 @@
+---
+title: Java Management
+description: Automatic Java detection, download, and installation
+---
+
+# Java Management
+
+DropOut provides comprehensive Java management, automatically detecting installed versions and downloading new ones as needed.
+
+## Auto-detection
+
+### System Scan
+
+DropOut scans multiple locations for Java installations:
+
+**Linux:**
+- `/usr/lib/jvm/`
+- `/usr/java/`
+- `$JAVA_HOME`
+- `PATH` environment variable
+
+**macOS:**
+- `/Library/Java/JavaVirtualMachines/`
+- `/System/Library/Java/JavaVirtualMachines/`
+- `$JAVA_HOME`
+- `PATH` environment variable
+
+**Windows:**
+- `C:\Program Files\Java\`
+- `C:\Program Files (x86)\Java\`
+- `%JAVA_HOME%`
+- `PATH` environment variable
+- Windows Registry
+
+### Version Detection
+
+For each Java installation found, DropOut:
+1. Runs `java -version` to get version info
+2. Parses major version (8, 11, 17, 21, etc.)
+3. Detects architecture (x64, ARM64)
+4. Identifies vendor (Oracle, Adoptium, etc.)
+
+### Results
+
+All detected Java installations appear in Settings → Java:
+- Version number
+- Installation path
+- Architecture
+- Current selection status
+
+## Java Download
+
+### Adoptium Integration
+
+DropOut integrates with the Eclipse Adoptium API to download high-quality, free JDK/JRE builds.
+
+**Supported Versions:**
+- Java 8 (LTS)
+- Java 11 (LTS)
+- Java 17 (LTS)
+- Java 21 (LTS)
+- Java 23+ (Latest)
+
+**Features:**
+- Automatic platform detection
+- Architecture-specific builds
+- JDK or JRE selection
+- Checksum verification
+
+### Download Process
+
+1. Navigate to Settings → Java
+2. Click "Download Java"
+3. Select version (e.g., Java 17)
+4. Choose JDK or JRE
+5. Click Download
+6. Wait for download and extraction
+
+**Progress Tracking:**
+- Real-time download speed
+- ETA calculation
+- Extraction progress
+- Installation confirmation
+
+### Catalog Management
+
+The Java catalog is cached for 24 hours to improve performance:
+
+```rust
+// Catalog structure
+{
+  "versions": [
+    {
+      "version": "17.0.9+9",
+      "major": 17,
+      "url": "https://api.adoptium.net/...",
+      "sha256": "...",
+      "size": 123456789
+    }
+  ],
+  "last_updated": 1234567890
+}
+```
+
+**Refresh:**
+- Automatic after 24 hours
+- Manual refresh in settings
+- Forced refresh on download failure
+
+## Installation
+
+### Download Directory
+
+Downloaded Java runtimes are installed to:
+
+```
+~/.local/share/com.dropout.launcher/java/  (Linux)
+~/Library/Application Support/com.dropout.launcher/java/  (macOS)
+%APPDATA%/com.dropout.launcher/java/  (Windows)
+```
+
+### Directory Structure
+
+```
+java/
+├── jdk-17.0.9+9/
+│   ├── bin/
+│   │   └── java (or java.exe)
+│   └── lib/
+├── jdk-21.0.1+12/
+│   ├── bin/
+│   └── lib/
+└── download_queue.json
+```
+
+### Extraction
+
+1. Download to `.part` file
+2. Verify checksum
+3. Extract archive:
+   - `.tar.gz` on Linux/macOS
+   - `.zip` on Windows
+4. Move to `java/<version>/` directory
+5. Set executable permissions (Unix)
+
+## Configuration
+
+### Memory Allocation
+
+Configure JVM memory in Settings:
+
+**Minimum Memory:**
+- Default: 1024 MB
+- Recommended: 2048 MB for vanilla
+- Recommended: 4096+ MB for modded
+
+**Maximum Memory:**
+- Default: 4096 MB
+- Adjust based on your system RAM
+- Leave 4GB for OS and other apps
+
+**Format:**
+```bash
+-Xms1024M -Xmx4096M
+```
+
+### Custom JVM Arguments
+
+Add custom JVM arguments for advanced configuration:
+
+**Common Arguments:**
+```bash
+# Garbage collection
+-XX:+UseG1GC
+-XX:+UnlockExperimentalVMOptions
+
+# Performance
+-XX:G1NewSizePercent=20
+-XX:G1ReservePercent=20
+-XX:MaxGCPauseMillis=50
+
+# Memory
+-XX:G1HeapRegionSize=32M
+```
+
+### Java Path Selection
+
+**Auto-select:**
+- DropOut recommends the best Java version for each Minecraft version
+- Java 8 for Minecraft 1.12.2 and older
+- Java 17 for Minecraft 1.18-1.20.4
+- Java 21 for Minecraft 1.20.5+
+
+**Manual selection:**
+1. Go to Settings → Java
+2. Choose from detected installations
+3. Or specify custom path
+
+## Version Recommendations
+
+### Minecraft Version → Java Version
+
+| Minecraft Version | Recommended Java | Minimum Java |
+|-------------------|------------------|--------------|
+| 1.7.10 and older  | Java 8           | Java 8       |
+| 1.8 - 1.12.2      | Java 8           | Java 8       |
+| 1.13 - 1.16.5     | Java 8 or 11     | Java 8       |
+| 1.17 - 1.17.1     | Java 16          | Java 16      |
+| 1.18 - 1.20.4     | Java 17          | Java 17      |
+| 1.20.5+           | Java 21          | Java 21      |
+
+### Modded Minecraft
+
+**Fabric:**
+- Usually matches vanilla requirements
+- Some mods may require newer Java
+
+**Forge:**
+- May require specific Java versions
+- Check mod loader documentation
+- Often requires exact version match
+
+## Troubleshooting
+
+### Java Not Detected
+
+**Issue:** Installed Java not showing up
+
+**Solutions:**
+1. Verify Java is in standard location
+2. Check `JAVA_HOME` environment variable
+3. Add Java `bin` directory to `PATH`
+4. Restart DropOut
+5. Manual path selection
+
+### Download Fails
+
+**Issue:** Java download doesn't complete
+
+**Solutions:**
+1. Check internet connection
+2. Verify disk space
+3. Try different version
+4. Clear download queue
+5. Manual download from Adoptium
+
+### Wrong Java Version
+
+**Issue:** Game crashes due to Java version
+
+**Solutions:**
+1. Check Minecraft version requirements
+2. Download correct Java version
+3. Select appropriate Java in settings
+4. Verify Java path is correct
+
+### OutOfMemoryError
+
+**Issue:** Game crashes with memory error
+
+**Solutions:**
+1. Increase maximum memory allocation
+2. Close other applications
+3. Upgrade system RAM
+4. Use 64-bit Java
+5. Optimize JVM arguments
+
+### Performance Issues
+
+**Issue:** Low FPS or stuttering
+
+**Solutions:**
+1. Adjust memory allocation (not too high!)
+2. Enable G1GC garbage collector
+3. Add performance JVM arguments
+4. Use newer Java version if compatible
+5. Allocate 4-8GB for modpacks
+
+## API Reference
+
+### Tauri Commands
+
+**Detect Java Installations:**
+```typescript
+const javas = await invoke('detect_java_installations');
+// Returns: Array<{ path: string, version: string, major: number }>
+```
+
+**Get Java Catalog:**
+```typescript
+const catalog = await invoke('get_java_catalog');
+// Returns: { versions: Array<JavaVersion>, last_updated: number }
+```
+
+**Download Java:**
+```typescript
+await invoke('download_java', { 
+  version: '17.0.9+9',
+  variant: 'jdk' // or 'jre'
+});
+```
+
+**Cancel Java Download:**
+```typescript
+await invoke('cancel_java_download');
+```
+
+**Set Java Path:**
+```typescript
+await invoke('set_java_path', { path: '/path/to/java' });
+```
+
+### Events
+
+**Download Progress:**
+```typescript
+listen('java-download-progress', (event) => {
+  const { percent, speed, eta } = event.payload;
+});
+```
+
+**Download Complete:**
+```typescript
+listen('java-download-complete', (event) => {
+  const { path, version } = event.payload;
+});
+```
+
+## Best Practices
+
+### For Players
+
+1. **Use Adoptium builds** - Free, high-quality, maintained
+2. **Match Java to Minecraft** - Check version requirements
+3. **Don't over-allocate memory** - Leave RAM for OS
+4. **Keep Java updated** - Security and performance
+5. **Use 64-bit Java** - Required for large memory
+
+### For Developers
+
+1. **Test multiple Java versions** - Ensure compatibility
+2. **Document Java requirements** - Help users
+3. **Handle missing Java** - Graceful fallbacks
+4. **Validate Java path** - Before launching
+5. **Provide clear errors** - When Java is wrong
+
+## Advanced Topics
+
+### Custom Java Installation
+
+To use a custom Java installation:
+
+1. Install Java manually
+2. Note the installation path
+3. In DropOut Settings → Java
+4. Click "Custom Path"
+5. Browse to Java executable
+6. Verify version is correct
+
+### Java for Servers
+
+When running a Minecraft server:
+
+```bash
+# Recommended server JVM arguments
+-Xms4G -Xmx4G \
+-XX:+UseG1GC \
+-XX:+ParallelRefProcEnabled \
+-XX:MaxGCPauseMillis=200 \
+-XX:+UnlockExperimentalVMOptions \
+-XX:+DisableExplicitGC \
+-XX:G1NewSizePercent=30 \
+-XX:G1MaxNewSizePercent=40 \
+-XX:G1HeapRegionSize=8M \
+-XX:G1ReservePercent=20 \
+-XX:G1HeapWastePercent=5 \
+-XX:G1MixedGCCountTarget=4 \
+-XX:InitiatingHeapOccupancyPercent=15 \
+-XX:G1MixedGCLiveThresholdPercent=90 \
+-XX:G1RSetUpdatingPauseTimePercent=5 \
+-XX:SurvivorRatio=32 \
+-XX:+PerfDisableSharedMem \
+-XX:MaxTenuringThreshold=1
+```
+
+### GraalVM
+
+GraalVM is supported for advanced users:
+
+1. Download GraalVM from graalvm.org
+2. Install manually
+3. Add to DropOut as custom Java
+4. May improve performance
+5. Test thoroughly before use
+
diff --git a/packages/docs/content/docs/features/meta.json b/packages/docs/content/docs/features/meta.json
new file mode 100644
index 0000000..4725321
--- /dev/null
+++ b/packages/docs/content/docs/features/meta.json
@@ -0,0 +1,9 @@
+{
+  "title": "Features",
+  "pages": [
+    "index",
+    "authentication",
+    "java",
+    "mod-loaders"
+  ]
+}
diff --git a/packages/docs/content/docs/features/mod-loaders.mdx b/packages/docs/content/docs/features/mod-loaders.mdx
new file mode 100644
index 0000000..a9616d6
--- /dev/null
+++ b/packages/docs/content/docs/features/mod-loaders.mdx
@@ -0,0 +1,410 @@
+---
+title: Mod Loaders
+description: Fabric and Forge installation and management
+---
+
+# Mod Loaders
+
+DropOut supports the two most popular Minecraft mod loaders: Fabric and Forge. Both can be easily installed and managed directly from the launcher.
+
+## Fabric Support
+
+### Overview
+
+Fabric is a lightweight, modular modding toolchain focused on:
+- Fast updates to new Minecraft versions
+- Clean, minimal API
+- Strong developer community
+- Excellent performance
+
+### Installation
+
+1. Navigate to **Versions** tab
+2. Click **"Install Fabric"**
+3. Select Minecraft version
+4. Choose Fabric loader version
+5. Click **"Install"**
+6. Wait for installation to complete
+
+### How It Works
+
+**Meta API Integration:**
+```rust
+// Fetch available Fabric versions
+let url = format!(
+    "https://meta.fabricmc.net/v2/versions/loader/{}",
+    minecraft_version
+);
+```
+
+**Profile Generation:**
+1. Fetch Fabric loader metadata
+2. Download Fabric libraries
+3. Generate version JSON with `inheritsFrom`
+4. Merge with parent Minecraft version
+5. Add to versions list
+
+**Version Format:**
+```json
+{
+  "id": "fabric-loader-0.15.0-1.20.4",
+  "inheritsFrom": "1.20.4",
+  "mainClass": "net.fabricmc.loader.impl.launch.knot.KnotClient",
+  "libraries": [...]
+}
+```
+
+### Fabric Versions
+
+**Loader Versions:**
+- Latest stable (recommended)
+- Specific versions for compatibility
+- Beta/snapshot versions
+
+**Game Versions:**
+- All Minecraft versions from 1.14+
+- Snapshots supported
+- Combat Test versions
+
+### Library Management
+
+Fabric libraries are resolved from Maven:
+
+**Main Library:**
+```
+net.fabricmc:fabric-loader:0.15.0
+```
+
+**Dependencies:**
+- `net.fabricmc:tiny-mappings-parser`
+- `net.fabricmc:sponge-mixin`
+- `net.fabricmc:access-widener`
+
+**Download:**
+```rust
+// Maven resolution
+let url = format!(
+    "https://maven.fabricmc.net/{}/{}",
+    artifact_path, filename
+);
+```
+
+### Fabric API
+
+Fabric Loader ≠ Fabric API:
+- **Fabric Loader**: Mod loader (installed by DropOut)
+- **Fabric API**: Library mod (download separately)
+
+Many mods require Fabric API:
+1. Download from [Modrinth](https://modrinth.com/mod/fabric-api) or [CurseForge](https://www.curseforge.com/minecraft/mc-mods/fabric-api)
+2. Place in instance's `mods/` folder
+
+## Forge Support
+
+### Overview
+
+Forge is the original and most popular Minecraft mod loader:
+- Extensive mod ecosystem
+- Mature API
+- Wide version support
+- Large community
+
+### Installation
+
+1. Navigate to **Versions** tab
+2. Click **"Install Forge"**
+3. Select Minecraft version
+4. Choose Forge version
+5. Click **"Install"**
+6. Wait for installer to run
+7. Installation complete
+
+### How It Works
+
+**Forge Installer:**
+```rust
+// Download Forge installer
+let installer_url = format!(
+    "https://maven.minecraftforge.net/net/minecraftforge/forge/{}/forge-{}-installer.jar",
+    full_version, full_version
+);
+
+// Run installer
+java -jar forge-installer.jar --installClient
+```
+
+**Profile Parsing:**
+1. Forge installer creates version JSON
+2. DropOut parses install profile
+3. Extracts library dependencies
+4. Processes processors (if any)
+5. Generates launcher profile
+
+**Version Format:**
+```json
+{
+  "id": "1.20.4-forge-49.0.26",
+  "inheritsFrom": "1.20.4",
+  "mainClass": "cpw.mods.bootstraplauncher.BootstrapLauncher",
+  "libraries": [...]
+}
+```
+
+### Forge Versions
+
+**Release Types:**
+- **Latest**: Most recent stable
+- **Recommended**: Most stable for production
+- **Specific**: Version-locked for compatibility
+
+**Minecraft Version Support:**
+- Legacy versions (1.6.4+)
+- Modern versions (1.13+)
+- Latest versions (1.20+)
+
+### Library Management
+
+Forge has many libraries:
+
+**Core Libraries:**
+- `net.minecraftforge:forge:<version>`
+- `net.minecraftforge:fmlloader:<version>`
+- `org.ow2.asm:asm:<version>`
+
+**Resolution:**
+```rust
+// Forge Maven
+"https://maven.minecraftforge.net/"
+
+// Dependencies may use:
+// - Maven Central
+// - Minecraft Libraries
+```
+
+### Forge Processors
+
+Some Forge versions run "processors" during installation:
+- Bytecode manipulation
+- Library patching
+- Mapping generation
+
+DropOut handles these automatically.
+
+## Version Inheritance
+
+Both Fabric and Forge use Minecraft's inheritance system:
+
+### Parent Version
+
+```json
+{
+  "id": "fabric-loader-0.15.0-1.20.4",
+  "inheritsFrom": "1.20.4"  // Parent vanilla version
+}
+```
+
+### Merging Process
+
+**Libraries:**
+```rust
+// Merged from both
+parent_libraries + modded_libraries
+// Duplicates removed
+```
+
+**Arguments:**
+```rust
+// Combined
+parent_jvm_args + modded_jvm_args
+parent_game_args + modded_game_args
+```
+
+**Assets:**
+```rust
+// Inherited from parent
+assets = parent.assets
+```
+
+**Main Class:**
+```rust
+// Overridden by modded
+main_class = modded.mainClass
+```
+
+## Comparison
+
+| Feature | Fabric | Forge |
+|---------|--------|-------|
+| **Performance** | Excellent | Good |
+| **Update Speed** | Very Fast | Moderate |
+| **Mod Selection** | Growing | Extensive |
+| **API Simplicity** | Simple | Complex |
+| **Version Support** | 1.14+ | 1.6.4+ |
+| **Developer Friendly** | Very | Moderate |
+| **Stability** | Excellent | Excellent |
+
+## Installing Mods
+
+### Fabric Mods
+
+1. Create/select instance
+2. Ensure Fabric is installed
+3. Download mods from:
+   - [Modrinth](https://modrinth.com/)
+   - [CurseForge](https://www.curseforge.com/)
+   - [GitHub Releases](https://github.com/)
+4. Place `.jar` files in `instances/<name>/mods/`
+5. Launch game
+
+**Compatibility:**
+- Check Minecraft version
+- Check Fabric Loader version
+- Check for Fabric API requirement
+- Read mod dependencies
+
+### Forge Mods
+
+1. Create/select instance
+2. Ensure Forge is installed
+3. Download mods from:
+   - [CurseForge](https://www.curseforge.com/)
+   - [Modrinth](https://modrinth.com/)
+4. Place `.jar` files in `instances/<name>/mods/`
+5. Launch game
+
+**Compatibility:**
+- Check Minecraft version exactly
+- Check Forge version range
+- Read mod dependencies
+- Check for conflicts
+
+## Troubleshooting
+
+### Fabric Issues
+
+**"Fabric Loader not found"**
+- Reinstall Fabric
+- Check version JSON exists
+- Verify libraries downloaded
+
+**"Mixin apply failed"**
+- Mod incompatibility
+- Remove conflicting mods
+- Update Fabric Loader
+
+**"Fabric API required"**
+- Download Fabric API
+- Match Minecraft version
+- Place in mods folder
+
+### Forge Issues
+
+**"Forge installer failed"**
+- Verify Java installation
+- Check disk space
+- Try older Forge version
+- Check logs for details
+
+**"Missing dependencies"**
+- Install required mods
+- Check mod version compatibility
+- Read error message carefully
+
+**"Class not found"**
+- Forge version mismatch
+- Reinstall Forge
+- Verify libraries downloaded
+
+### General Mod Issues
+
+**Crash on Launch:**
+1. Check crash report
+2. Identify problematic mod
+3. Remove or update mod
+4. Test with minimal mods
+5. Add mods back incrementally
+
+**Performance Problems:**
+1. Too many mods installed
+2. Increase memory allocation
+3. Install performance mods:
+   - Fabric: Sodium, Lithium
+   - Forge: OptiFine, Magnesium
+4. Remove resource-heavy mods
+
+## API Reference
+
+### Tauri Commands
+
+**Install Fabric:**
+```typescript
+await invoke('install_fabric', {
+  minecraftVersion: '1.20.4',
+  loaderVersion: '0.15.0'
+});
+```
+
+**Install Forge:**
+```typescript
+await invoke('install_forge', {
+  minecraftVersion: '1.20.4',
+  forgeVersion: '49.0.26'
+});
+```
+
+**List Fabric Versions:**
+```typescript
+const versions = await invoke('get_fabric_versions', {
+  minecraftVersion: '1.20.4'
+});
+```
+
+**List Forge Versions:**
+```typescript
+const versions = await invoke('get_forge_versions', {
+  minecraftVersion: '1.20.4'
+});
+```
+
+### Events
+
+**Installation Progress:**
+```typescript
+listen('mod-loader-progress', (event) => {
+  const { stage, percent } = event.payload;
+  // Stages: "downloading", "installing", "processing", "complete"
+});
+```
+
+## Best Practices
+
+### For Players
+
+1. **Choose one mod loader** per instance
+2. **Match versions exactly** - Minecraft and loader
+3. **Read mod requirements** before installing
+4. **Start small** - Add mods incrementally
+5. **Backup worlds** before adding mods
+6. **Check compatibility** lists
+7. **Update cautiously** - Test in separate instance
+
+### For Modpack Creators
+
+1. **Document versions** - MC, loader, all mods
+2. **Test thoroughly** - All features
+3. **List dependencies** - Including API
+4. **Provide changelog** - For updates
+5. **Version lock** - For stability
+6. **Include configs** - Pre-configured
+7. **Test updates** - Before release
+
+## Future Features
+
+- **Mod browser** - Install mods from launcher
+- **Automatic updates** - Keep mods current
+- **Dependency resolution** - Auto-install requirements
+- **Conflict detection** - Warn about incompatibilities
+- **Profile export** - Share modpack configurations
+- **CurseForge integration** - Direct modpack import
+- **Modrinth integration** - Mod search and install
+
diff --git a/packages/docs/content/docs/getting-started.mdx b/packages/docs/content/docs/getting-started.mdx
new file mode 100644
index 0000000..ac0fc1c
--- /dev/null
+++ b/packages/docs/content/docs/getting-started.mdx
@@ -0,0 +1,162 @@
+---
+title: Getting Started
+description: Quick start guide to using DropOut Minecraft Launcher
+---
+
+# Getting Started
+
+DropOut is a modern, reproducible, and developer-grade Minecraft launcher built with Tauri v2 and Rust. This guide will help you get started with installing and using DropOut.
+
+## Installation
+
+### Download Pre-built Binaries
+
+Download the latest release for your platform from the [Releases](https://github.com/HsiangNianian/DropOut/releases) page.
+
+| Platform       | Files                   |
+| -------------- | ----------------------- |
+| Linux x86_64   | `.deb`, `.AppImage`     |
+| Linux ARM64    | `.deb`, `.AppImage`     |
+| macOS ARM64    | `.dmg`                  |
+| Windows x86_64 | `.msi`, `.exe`          |
+| Windows ARM64  | `.msi`, `.exe`          |
+
+### Linux Installation
+
+#### Using .deb Package
+```bash
+sudo dpkg -i dropout_*.deb
+# Fix dependencies if needed
+sudo apt-get install -f
+```
+
+#### Using AppImage
+```bash
+chmod +x dropout_*.AppImage
+./dropout_*.AppImage
+```
+
+### macOS Installation
+
+1. Open the downloaded `.dmg` file
+2. Drag DropOut to your Applications folder
+3. If you see a security warning, go to System Preferences → Security & Privacy and allow the app
+
+### Windows Installation
+
+#### Using .msi Installer
+1. Double-click the `.msi` file
+2. Follow the installation wizard
+3. Launch DropOut from the Start Menu
+
+#### Using .exe Portable
+1. Double-click the `.exe` file
+2. DropOut will run directly without installation
+
+## First Launch
+
+When you first launch DropOut, you'll need to:
+
+1. **Choose Authentication Method**
+   - **Microsoft Account**: Recommended for official Minecraft
+   - **Offline Mode**: For testing or offline play
+
+2. **Configure Java Runtime**
+   - DropOut will automatically detect installed Java versions
+   - You can download Java directly from the launcher if needed
+
+3. **Select Minecraft Version**
+   - Browse available Minecraft versions
+   - Choose vanilla or modded versions (Fabric/Forge)
+
+## Quick Start Tutorial
+
+### 1. Login
+
+<Cards>
+  <Card 
+    title="Microsoft Account" 
+    description="Login with your official Minecraft account"
+  />
+  <Card 
+    title="Offline Mode" 
+    description="Create a local profile for offline play"
+  />
+</Cards>
+
+**Microsoft Login:**
+1. Click "Login with Microsoft"
+2. A device code will be displayed
+3. Visit the URL shown and enter the code
+4. Authorize the application
+5. Return to DropOut - you'll be logged in automatically
+
+**Offline Login:**
+1. Click "Offline Mode"
+2. Enter a username
+3. Click "Create Account"
+
+### 2. Install Minecraft
+
+1. Navigate to the **Versions** tab
+2. Browse available Minecraft versions
+3. Click on a version to install it
+4. Wait for the download to complete
+
+### 3. Launch the Game
+
+1. Go to the **Home** tab
+2. Select your desired version from the dropdown
+3. Adjust settings if needed:
+   - Memory allocation (RAM)
+   - Window resolution
+   - Java path
+4. Click **"Launch Game"**
+5. Monitor the launch process in the console
+
+## Next Steps
+
+<Cards>
+  <Card 
+    title="Features" 
+    href="/docs/features"
+    description="Learn about all the features DropOut offers"
+  />
+  <Card 
+    title="Instances" 
+    href="/docs/features/instances"
+    description="Create isolated game environments"
+  />
+  <Card 
+    title="Mod Loaders" 
+    href="/docs/features/mod-loaders"
+    description="Install and manage Fabric and Forge"
+  />
+  <Card 
+    title="Troubleshooting" 
+    href="/docs/troubleshooting"
+    description="Common issues and solutions"
+  />
+</Cards>
+
+## System Requirements
+
+### Minimum Requirements
+- **OS**: Windows 10+, macOS 11+, or Linux (Debian-based)
+- **RAM**: 4GB (8GB recommended for modded Minecraft)
+- **Storage**: 2GB for launcher + game files
+- **Java**: Auto-installed by DropOut if not found
+
+### Recommended Requirements
+- **OS**: Latest stable version of your OS
+- **RAM**: 16GB for optimal performance with mods
+- **Storage**: 10GB+ for multiple versions and mods
+- **Java**: Java 17 or 21 (managed by DropOut)
+
+## Getting Help
+
+If you encounter issues:
+- Check the [Troubleshooting Guide](/docs/troubleshooting)
+- Report bugs on [GitHub Issues](https://github.com/HsiangNianian/DropOut/issues)
+- Join our community discussions
+
diff --git a/packages/docs/content/docs/index.mdx b/packages/docs/content/docs/index.mdx
index 6c2e629..97e6228 100644
--- a/packages/docs/content/docs/index.mdx
+++ b/packages/docs/content/docs/index.mdx
@@ -1,32 +1,95 @@
 ---
-title: Hello World
-description: |
-  Your first `document`
-  You'll love it!
+title: Welcome to DropOut
+description: Modern, reproducible, and developer-grade Minecraft launcher
 ---
 
-Hey there! Fumadocs is the docs framework that also works on React Router!
+# Welcome to DropOut
 
-## Heading
+DropOut is a modern Minecraft launcher built with Tauri v2 and Rust, designed for players who value control, transparency, and long-term stability.
 
-Hello World
+<div style="text-align: center; margin: 2rem 0;">
+  <img src="/assets/image.png" alt="DropOut Launcher" style="max-width: 700px; border-radius: 8px;" />
+</div>
+
+## Why DropOut?
+
+Most Minecraft launchers focus on getting you into the game. DropOut focuses on keeping your game **stable**, **debuggable**, and **reproducible**.
+
+- Your instance worked yesterday but broke today? → **DropOut makes it traceable.**
+- Sharing a modpack means zipping gigabytes? → **DropOut shares exact dependency manifests.**
+- Java, loader, mods, configs drift out of sync? → **DropOut locks them together.**
+
+This launcher is built for players who value control, transparency, and long-term stability.
+
+## Quick Links
 
 <Cards>
-  <Card title="Learn more about React Router" href="https://reactrouter.com" />
-  <Card title="Learn more about Fumadocs" href="https://fumadocs.dev" />
+  <Card 
+    title="Getting Started" 
+    href="/docs/getting-started"
+    description="Install and set up DropOut in minutes"
+  />
+  <Card 
+    title="Features" 
+    href="/docs/features"
+    description="Explore all the capabilities of DropOut"
+  />
+  <Card 
+    title="Architecture" 
+    href="/docs/architecture"
+    description="Learn about the technical design"
+  />
+  <Card 
+    title="Development" 
+    href="/docs/development"
+    description="Build and contribute to DropOut"
+  />
 </Cards>
 
-```ts
-console.log('I love React!');
-```
+## Key Features
+
+### 🚀 High Performance
+Built with Rust and Tauri for minimal resource usage and fast startup times.
+
+### 🎨 Modern UI
+Clean, distraction-free interface with Svelte 5, Tailwind CSS 4, and particle effects.
+
+### 🔐 Secure Authentication
+Microsoft OAuth 2.0 with device code flow and offline authentication support.
+
+### 🔧 Mod Loader Support
+Built-in installation for Fabric and Forge with automatic version management.
+
+### ☕ Java Management
+Automatic detection of installed Java versions and integrated downloader for Adoptium JDK/JRE.
 
-### Heading
+### 📦 Instance System
+Isolated game environments with independent configurations, mods, and saves.
 
-#### Heading
+### 🤖 AI Assistant
+Built-in AI helper for troubleshooting, configuration, and guidance.
+
+### ⚡ Fast Downloads
+Concurrent asset and library downloads with resume support and progress tracking.
+
+## Technology Stack
+
+- **Backend**: Rust with Tauri v2
+- **Frontend**: Svelte 5 with runes
+- **Styling**: Tailwind CSS 4
+- **Build Tool**: Vite with Rolldown
+- **Documentation**: Fumadocs with React Router
+
+## Community
+
+- **GitHub**: [HydroRoll-Team/DropOut](https://github.com/HydroRoll-Team/DropOut)
+- **Issues**: [Report bugs](https://github.com/HydroRoll-Team/DropOut/issues)
+- **Roadmap**: [View development roadmap](https://roadmap.sh/r/minecraft-launcher-dev)
+
+## License
+
+DropOut is open source software licensed under the MIT License.
+
+---
 
-| Head                            | Description                         |
-| ------------------------------- | ----------------------------------- |
-| `hello`                         | Hello World                         |
-| very **important**              | Hey                                 |
-| _Surprisingly_                  | Fumadocs                            |
-| very long text that looks weird | hello world hello world hello world |
+Ready to get started? Check out the [Getting Started Guide](/docs/getting-started)!
diff --git a/packages/docs/content/docs/meta.json b/packages/docs/content/docs/meta.json
index bc00362..8ad7ea2 100644
--- a/packages/docs/content/docs/meta.json
+++ b/packages/docs/content/docs/meta.json
@@ -1,3 +1,19 @@
 {
-  "pages": ["index", "..."]
+  "title": "Documentation",
+  "pages": [
+    "index",
+    "getting-started",
+    "architecture",
+    {
+      "title": "Features",
+      "pages": [
+        "features/index",
+        "features/authentication",
+        "features/java",
+        "features/mod-loaders"
+      ]
+    },
+    "development",
+    "troubleshooting"
+  ]
 }
diff --git a/packages/docs/content/docs/test.mdx b/packages/docs/content/docs/test.mdx
deleted file mode 100644
index cac4d26..0000000
--- a/packages/docs/content/docs/test.mdx
+++ /dev/null
@@ -1,24 +0,0 @@
----
-title: Test
-description: A document to test Fumadocs
----
-
-Hey there!
-
-## Cards
-
-<Cards>
-  <Card title="Learn more about Next.js" href="https://nextjs.org/docs" />
-  <Card title="Learn more about Fumadocs" href="https://fumadocs.dev" />
-</Cards>
-
-### CodeBlock
-
-```js
-console.log('Hello World');
-```
-
-#### List
-
-- Hello
-- World
diff --git a/packages/docs/content/docs/troubleshooting.mdx b/packages/docs/content/docs/troubleshooting.mdx
new file mode 100644
index 0000000..33464d2
--- /dev/null
+++ b/packages/docs/content/docs/troubleshooting.mdx
@@ -0,0 +1,524 @@
+---
+title: Troubleshooting
+description: Common issues and solutions for DropOut launcher
+---
+
+# Troubleshooting
+
+This guide covers common issues and their solutions. If you don't find your issue here, please [open an issue](https://github.com/HydroRoll-Team/DropOut/issues) on GitHub.
+
+## Installation Issues
+
+### Linux: Missing Dependencies
+
+**Issue:** Error about missing libraries during installation
+
+**Solution:**
+```bash
+# Ubuntu/Debian
+sudo apt update
+sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0
+
+# Fedora
+sudo dnf install webkit2gtk4.1 gtk3
+
+# Arch
+sudo pacman -S webkit2gtk gtk3
+```
+
+### macOS: "App is damaged"
+
+**Issue:** macOS says DropOut is damaged and can't be opened
+
+**Solution:**
+1. Open Terminal
+2. Run: `xattr -cr /Applications/DropOut.app`
+3. Try opening again
+4. Or: System Preferences → Security → Allow anyway
+
+### Windows: SmartScreen Warning
+
+**Issue:** Windows SmartScreen blocks the installer
+
+**Solution:**
+1. Click "More info"
+2. Click "Run anyway"
+3. This is normal for new apps without extended validation certificates
+
+## Authentication Issues
+
+### Microsoft Login Fails
+
+**Issue:** Can't complete Microsoft login
+
+**Possible causes and solutions:**
+
+**1. Device code expired:**
+- Codes expire after 15 minutes
+- Start the login process again
+- Complete authorization faster
+
+**2. Network issues:**
+- Check internet connection
+- Disable VPN temporarily
+- Check firewall settings
+- Try different network
+
+**3. Microsoft account issues:**
+- Verify account owns Minecraft Java Edition
+- Check at https://www.minecraft.net/profile
+- Ensure account is not suspended
+
+**4. Browser problems:**
+- Try different browser
+- Clear browser cache
+- Disable ad blockers
+- Use incognito/private mode
+
+### Token Refresh Fails
+
+**Issue:** Token refresh fails, must re-login frequently
+
+**Solution:**
+1. Log out completely
+2. Delete `accounts.json` from app data directory
+3. Log in again
+4. If persists, check Microsoft account status
+
+### Offline Login Not Working
+
+**Issue:** Can't create offline account
+
+**Solution:**
+- Username must be 3-16 characters
+- Use only letters, numbers, underscore
+- No special characters
+- No spaces
+
+## Game Launch Issues
+
+### Java Not Found
+
+**Issue:** "No Java installation found"
+
+**Solutions:**
+
+**1. Auto-detect existing Java:**
+- Settings → Java → Detect Installations
+- If found, select it
+- If not found, proceed to step 2
+
+**2. Download Java via DropOut:**
+- Settings → Java → Download Java
+- Select appropriate version:
+  - Java 8 for Minecraft 1.12.2 and older
+  - Java 17 for Minecraft 1.18-1.20.4
+  - Java 21 for Minecraft 1.20.5+
+
+**3. Manual Java installation:**
+- Download from [Adoptium](https://adoptium.net/)
+- Install to system
+- Restart DropOut
+- Detect again
+
+### Wrong Java Version
+
+**Issue:** Game crashes with "Unsupported class file version"
+
+**Solution:**
+Match Java version to Minecraft version:
+
+| Minecraft Version | Java Version |
+|-------------------|--------------|
+| 1.7.10 and older  | Java 8       |
+| 1.8 - 1.12.2      | Java 8       |
+| 1.13 - 1.16.5     | Java 8 or 11 |
+| 1.17 - 1.17.1     | Java 16      |
+| 1.18 - 1.20.4     | Java 17      |
+| 1.20.5+           | Java 21      |
+
+### OutOfMemoryError
+
+**Issue:** Game crashes with `java.lang.OutOfMemoryError`
+
+**Solutions:**
+
+**1. Increase memory allocation:**
+- Settings → Memory
+- Increase Maximum Memory:
+  - Vanilla: 4GB minimum
+  - Light mods: 6GB
+  - Heavy modpacks: 8-12GB
+- Don't exceed 80% of system RAM
+
+**2. Use 64-bit Java:**
+- Check current Java architecture
+- Download 64-bit Java if needed
+- 32-bit Java limited to ~2GB
+
+**3. Reduce render distance:**
+- In-game Video Settings
+- Lower render distance to 8-12 chunks
+
+**4. Optimize JVM arguments:**
+```bash
+-Xms4G -Xmx8G -XX:+UseG1GC -XX:+UnlockExperimentalVMOptions
+```
+
+### Game Won't Start
+
+**Issue:** Game doesn't launch, no error message
+
+**Check:**
+
+**1. Log output:**
+- Check game console in DropOut
+- Look for error messages
+- Common issues:
+  - Missing files
+  - Corrupted downloads
+  - Mod conflicts
+
+**2. Verify files:**
+- Delete version folder
+- Re-download version
+- Try vanilla first before modded
+
+**3. Check permissions:**
+- Ensure DropOut can write to game directory
+- Check folder permissions
+- On Linux: `chmod -R 755 ~/.local/share/com.dropout.launcher`
+
+## Download Issues
+
+### Downloads Fail
+
+**Issue:** Asset or library downloads fail
+
+**Solutions:**
+
+**1. Network issues:**
+- Check internet connection
+- Disable VPN
+- Try different network
+- Check firewall/antivirus
+
+**2. Resume downloads:**
+- DropOut auto-resumes interrupted downloads
+- Close and reopen DropOut
+- Downloads should continue
+
+**3. Clear download cache:**
+- Delete `.part` files in libraries/assets
+- Restart download
+
+**4. Manually download:**
+- Check logs for failing URL
+- Download file manually
+- Place in correct location
+
+### Slow Downloads
+
+**Issue:** Downloads are very slow
+
+**Solutions:**
+
+**1. Adjust thread count:**
+- Settings → Downloads
+- Try different thread counts:
+  - Too low: slow overall
+  - Too high: connection throttling
+  - Recommended: 5-10 threads
+
+**2. Network optimization:**
+- Close bandwidth-heavy apps
+- Use wired connection if possible
+- Check for ISP throttling
+
+**3. Alternative CDN:**
+- Mojang mirrors may be slow
+- Try at different time of day
+
+## Mod Loader Issues
+
+### Fabric Installation Fails
+
+**Issue:** Can't install Fabric loader
+
+**Solutions:**
+
+**1. Check Minecraft version:**
+- Fabric supports 1.14+
+- Older versions not supported
+- Try newer Minecraft version
+
+**2. Network issues:**
+- Check internet connection
+- Fabric Meta API may be down
+- Try again later
+
+**3. Manual installation:**
+- Download Fabric from [fabricmc.net](https://fabricmc.net/)
+- Use official installer
+- Import profile to DropOut
+
+### Forge Installation Fails
+
+**Issue:** Forge installer fails or hangs
+
+**Solutions:**
+
+**1. Java version:**
+- Ensure correct Java version
+- Forge 1.17+ requires Java 16+
+- Older Forge may need Java 8
+
+**2. Installer timeout:**
+- Forge installer can be slow
+- Wait up to 10 minutes
+- Check logs for progress
+
+**3. Disk space:**
+- Ensure sufficient free space
+- Forge needs ~1GB temporarily
+- Check `/tmp` on Linux
+
+**4. Manual installation:**
+- Download Forge installer from [minecraftforge.net](https://files.minecraftforge.net/)
+- Run installer manually
+- Select install client
+- Import profile
+
+### Mod Crashes
+
+**Issue:** Game crashes with mods installed
+
+**Solutions:**
+
+**1. Check compatibility:**
+- Verify mod is for correct Minecraft version
+- Check mod loader version requirements
+- Read mod description for dependencies
+
+**2. Install dependencies:**
+- Fabric mods often need Fabric API
+- Some mods require libraries
+- Check crash log for "missing" errors
+
+**3. Remove conflicting mods:**
+- Disable mods one by one
+- Identify problematic mod
+- Check for known conflicts
+- Update or replace mod
+
+**4. Update mods:**
+- Use latest mod versions
+- Check mod update notes
+- Some updates fix crashes
+
+## Performance Issues
+
+### Low FPS
+
+**Issue:** Game runs slowly or stutters
+
+**Solutions:**
+
+**1. Allocate more memory:**
+- Increase max memory to 6-8GB
+- Don't over-allocate (causes GC pauses)
+
+**2. Install performance mods:**
+- **Fabric**: Sodium, Lithium, Phosphor
+- **Forge**: OptiFine, Magnesium, Rubidium
+
+**3. Optimize settings:**
+- Lower render distance
+- Disable fancy graphics
+- Turn off particles
+- Disable VSync if fps < 60
+
+**4. Update graphics drivers:**
+- Download latest from manufacturer
+- NVIDIA: GeForce Experience
+- AMD: Adrenalin
+- Intel: Graphics Command Center
+
+**5. Close background apps:**
+- Free up system resources
+- Disable overlays (Discord, etc.)
+- Check Task Manager for CPU/RAM hogs
+
+### Launcher Slow to Start
+
+**Issue:** DropOut takes long time to launch
+
+**Solutions:**
+
+**1. Check system resources:**
+- Close unnecessary programs
+- Ensure sufficient RAM available
+- Check CPU usage
+
+**2. Antivirus interference:**
+- Add DropOut to exceptions
+- Temporarily disable to test
+- Some AVs slow down significantly
+
+**3. Corrupted data:**
+- Delete `cache` folder in app data
+- Restart DropOut
+- Will rebuild cache
+
+## UI Issues
+
+### Window Won't Open
+
+**Issue:** DropOut window doesn't appear
+
+**Solutions:**
+
+**1. Check if running:**
+```bash
+# Linux/macOS
+ps aux | grep dropout
+
+# Windows
+tasklist | findstr dropout
+```
+
+**2. Kill and restart:**
+```bash
+# Linux/macOS
+pkill dropout
+
+# Windows
+taskkill /F /IM dropout.exe
+```
+
+**3. Reset window position:**
+- Delete window state config
+- Restart DropOut
+
+### Graphics Glitches
+
+**Issue:** UI looks wrong or has visual artifacts
+
+**Solutions:**
+
+**1. Update graphics drivers:**
+- Install latest drivers
+- Restart system
+
+**2. Disable hardware acceleration:**
+- Check if option exists in settings
+- May reduce performance but fix glitches
+
+**3. Try different monitor:**
+- Multi-monitor setups can cause issues
+- Try on different display
+
+## File System Issues
+
+### Can't Access Game Directory
+
+**Issue:** Errors accessing game files
+
+**Solutions:**
+
+**1. Check permissions:**
+```bash
+# Linux
+chmod -R 755 ~/.local/share/com.dropout.launcher
+
+# macOS
+chmod -R 755 ~/Library/Application\ Support/com.dropout.launcher
+```
+
+**2. Check disk space:**
+- Ensure sufficient free space
+- Minecraft needs 2-10GB depending on mods
+- Clean up old versions
+
+**3. Antivirus blocking:**
+- Add game directory to exceptions
+- Some AVs block file access
+
+### Corrupted Files
+
+**Issue:** Files appear corrupted or invalid
+
+**Solutions:**
+
+**1. Verify checksums:**
+- DropOut verifies SHA1/SHA256
+- Failed verification triggers re-download
+
+**2. Re-download:**
+- Delete corrupted file
+- Launch version again
+- DropOut will re-download
+
+**3. Clear cache:**
+- Delete version folder entirely
+- Re-install from scratch
+
+## Getting More Help
+
+### Collect Debug Information
+
+When reporting issues, include:
+
+**1. System information:**
+- OS and version
+- DropOut version
+- Java version
+
+**2. Logs:**
+- Launcher logs from console
+- Game logs if applicable
+- Error messages (full text)
+
+**3. Steps to reproduce:**
+- What you did
+- What you expected
+- What actually happened
+
+**4. Screenshots:**
+- Error messages
+- UI issues
+- Settings screens
+
+### Report Issues
+
+1. Search [existing issues](https://github.com/HydroRoll-Team/DropOut/issues)
+2. If not found, [create new issue](https://github.com/HydroRoll-Team/DropOut/issues/new)
+3. Use issue template
+4. Provide all requested information
+5. Be patient and responsive
+
+### Community Support
+
+- **GitHub Discussions**: Ask questions
+- **Discord**: Real-time help (if available)
+- **Documentation**: Check all guides
+
+## Known Issues
+
+### Currently Being Worked On
+
+- Multi-account switching (in progress)
+- Custom game directory selection (planned)
+- Launcher auto-update (planned)
+
+### Workarounds Available
+
+**Issue**: Can't switch between accounts easily
+**Workaround**: Log out and log in with different account
+
+**Issue**: No built-in mod manager
+**Workaround**: Manually manage mods in instance folder
+
+**Issue**: Can't import from other launchers
+**Workaround**: Manually copy instance files
+