diff --git a/Troubleshooting.md b/Troubleshooting.md
new file mode 100644
index 0000000..0d8e088
--- /dev/null
+++ b/Troubleshooting.md
@@ -0,0 +1,355 @@
+# Troubleshooting
+
+Having problems? Find your issue below and follow the steps.
+
+## Table of Contents
+
+- ["I see 'docker: command not found'"](#i-see-docker-command-not-found)
+- ["I see 'permission denied' when running docker"](#i-see-permission-denied-when-running-docker)
+- ["I see 'port already in use'"](#i-see-port-already-in-use)
+- ["The page won't load in my browser"](#the-page-wont-load-in-my-browser)
+- ["Services show 'unhealthy' or 'starting'"](#services-show-unhealthy-or-starting)
+- ["I forgot the login password"](#i-forgot-the-login-password)
+- ["I can't log in after deleting the default admin account"](#i-cant-log-in-after-deleting-the-default-admin-account)
+- ["API key test fails"](#api-key-test-fails)
+- ["Models not appearing in the list"](#models-not-appearing-in-the-list)
+- ["Agent doesn't use my dataset"](#agent-doesnt-use-my-dataset)
+- ["Document stuck in 'Processing'"](#document-stuck-in-processing)
+- ["I'm locked out due to Two-Factor Authentication (TFA)"](#im-locked-out-due-to-two-factor-authentication-tfa)
+- ["My AI agent doesn't respond"](#my-ai-agent-doesnt-respond)
+- ["How do I see what's happening behind the scenes?"](#how-do-i-see-whats-happening-behind-the-scenes)
+- ["I want to start completely fresh (delete everything)"](#i-want-to-start-completely-fresh-delete-everything)
+- ["Nothing above helped - I need more support"](#nothing-above-helped---i-need-more-support)
+
+---
+
+## "I see 'docker: command not found'"
+
+**What this means:** Docker isn't installed on your computer.
+
+**How to fix it:**
+
+1. Go back to the [Installation section in the README](https://github.com/GT-Edge-AI-Internal/gt-ai-os-community#installation)
+2. Follow the steps for your computer type to install Docker Desktop
+3. Make sure Docker is running before trying again
+
+---
+
+## "I see 'permission denied' when running docker"
+
+**What this means:** Your computer user account doesn't have permission to use Docker.
+
+**How to fix it (Ubuntu/Linux only):**
+
+1. Open Terminal
+2. Copy and paste this command, then press Enter:
+   ```bash
+   sudo usermod -aG docker $USER
+   ```
+3. Type your password when asked (you won't see characters as you type - that's normal)
+4. **Important:** You must log out of your computer completely, then log back in
+5. Try your command again
+
+---
+
+## "I see 'port already in use'"
+
+**What this means:** Another program on your computer is using the same connection port that GT AI OS needs.
+
+**How to fix it:**
+
+1. Open Terminal
+2. Go to your GT AI OS folder:
+   ```bash
+   cd ~/Desktop/gt-ai-os-community
+   ```
+   (Or wherever you installed it)
+3. Stop everything:
+   ```bash
+   docker compose down
+   ```
+4. Wait 10 seconds, then start again:
+   ```bash
+   docker compose up -d
+   ```
+
+**Still not working?** Restart your computer and try again.
+
+---
+
+## "The page won't load in my browser"
+
+**What this means:** Either Docker isn't running, or the services haven't started yet.
+
+**How to fix it:**
+
+**Step 1: Check if Docker is running**
+
+- **Ubuntu/DGX:** Open Terminal and type:
+  ```bash
+  docker ps
+  ```
+  - If you see a list of containers, Docker is running
+  - If you see an error, start Docker with: `sudo systemctl start docker`
+- **macOS:** Look at the top-right of your screen (menu bar). Do you see a whale icon?
+  - If yes, Docker is running
+  - If no, open the **Docker** app from your Applications folder
+
+**Step 2: Wait for services to start**
+
+After starting GT AI OS, wait 2-3 minutes for everything to load. The first time takes longer.
+
+**Step 3: Try a different browser**
+
+If one browser doesn't work, try another (Chrome, Firefox, Safari).
+
+**Step 4: Check if services are running**
+
+Open Terminal and type:
+```bash
+docker ps
+```
+
+You should see about 10 containers listed. If you see fewer, or none, run:
+```bash
+cd ~/Desktop/gt-ai-os-community
+docker compose up -d
+```
+
+---
+
+## "Services show 'unhealthy' or 'starting'"
+
+**What this means:** The services are still loading. This is normal!
+
+**How to fix it:**
+
+1. Wait 2-3 minutes
+2. Refresh your browser page
+3. If still unhealthy after 5 minutes, restart everything:
+   ```bash
+   cd ~/Desktop/gt-ai-os-community
+   docker compose down
+   docker compose up -d
+   ```
+
+---
+
+## "I forgot the login password"
+
+**Default login credentials:**
+- **Email:** `gtadmin@test.com`
+- **Password:** `Test@123`
+
+These work for both the Control Panel (http://localhost:3001) and Tenant App (http://localhost:3002).
+
+**If you deleted the default account:** You'll need to reset the database. See "I want to start completely fresh" below.
+
+---
+
+## "I can't log in after deleting the default admin account"
+
+**What this means:** You deleted `gtadmin@test.com` before verifying your new account works.
+
+**How to fix it:**
+
+1. Open Terminal
+2. Go to your GT AI OS folder:
+   ```bash
+   cd ~/gt-ai-os-community          # Ubuntu/DGX
+   cd ~/Desktop/gt-ai-os-community  # macOS
+   ```
+3. Reset the database:
+   ```bash
+   docker compose down -v
+   docker compose up -d
+   ```
+4. Wait 2-3 minutes for services to start
+5. Log in with the default credentials: `gtadmin@test.com` / `Test@123`
+6. **This time:** Verify your new account works BEFORE deleting the default one
+
+---
+
+## "API key test fails"
+
+**For NVIDIA API keys:**
+- Make sure you copied the complete key (some are longer than expected)
+- Verify your account is active at https://build.nvidia.com/
+- Check that the key hasn't expired
+
+**For Groq API keys:**
+- Make sure your key starts with `gsk_`
+- Check that your Groq account is active at https://console.groq.com/
+- Verify the key isn't deactivated in your Groq dashboard
+
+**General tips:**
+- Don't include extra spaces before or after the key
+- Try generating a new key if the current one doesn't work
+
+---
+
+## "Models not appearing in the list"
+
+**What this means:** The Models page is empty or missing expected models.
+
+**How to fix it:**
+
+1. **Check that you have an API key configured:**
+   - Go to Control Panel → API Keys
+   - You should see at least one key (NVIDIA or Groq)
+   - If no keys exist, add one first (see [Control Panel Guide](Control-Panel-Guide))
+
+2. **Match providers:**
+   - NVIDIA models require an NVIDIA API key
+   - Groq models require a Groq API key
+
+3. **Try refreshing:**
+   - Press F5 or Cmd+R to refresh the page
+   - Wait 10 seconds and check again
+
+4. **Restart the backend:**
+   ```bash
+   docker compose restart control-panel-backend
+   ```
+
+5. **If still empty, reset the database:**
+   - Models are loaded automatically during installation
+   - If missing, you may need to reinstall (see "I want to start completely fresh" below)
+
+---
+
+## "Agent doesn't use my dataset"
+
+**What this means:** You connected a dataset to an agent, but it doesn't seem to use the documents.
+
+**How to fix it:**
+
+1. **Check document processing status:**
+   - Go to Tenant App → Datasets
+   - Click on your dataset
+   - All documents should show **Completed** status
+   - If any show **Processing** or **Failed**, wait or re-upload
+
+2. **Verify the dataset is connected:**
+   - Go to Tenant App → Agents
+   - Edit your agent
+   - Check the **Datasets** section - your dataset should be selected
+   - Save if you made changes
+
+3. **Ask about your documents:**
+   - Try asking a specific question about content in your documents
+   - Example: "What does my document say about [specific topic]?"
+
+---
+
+## "Document stuck in 'Processing'"
+
+**What this means:** A document upload hasn't completed processing.
+
+**How to fix it:**
+
+1. **Wait longer:** Large documents (especially PDFs) can take several minutes
+2. **Check the file type:** Supported formats are PDF, DOCX, TXT, MD, JSON, CSV
+3. **Check file size:** Very large files may timeout
+4. **Try re-uploading:**
+   - Delete the stuck document
+   - Upload again
+5. **Check if embeddings service is running:**
+   ```bash
+   docker ps | grep vllm-embeddings
+   ```
+   - If not running, restart: `docker compose restart vllm-embeddings`
+
+---
+
+## "I'm locked out due to Two-Factor Authentication (TFA)"
+
+**What this means:** You enabled TFA but lost access to your authenticator app.
+
+**How to fix it:**
+
+You'll need to reset the database (this deletes all data):
+
+1. Follow the steps in "I want to start completely fresh" below
+2. After reset, log in with default credentials
+3. Set up your new account and enable TFA again
+
+---
+
+## "My AI agent doesn't respond"
+
+**What this means:** The AI model might not be connected or configured correctly.
+
+**How to fix it:**
+
+1. **Check if you have a model configured:**
+   - Open Control Panel: http://localhost:3001
+   - Go to **Models** in the left sidebar
+   - You should see at least one model listed
+   - If empty, you need to [set up Ollama](Ollama-Setup) or add an API-based model
+
+2. **Check if the model is assigned to your tenant:**
+   - In Control Panel, go to **Tenant Access**
+   - Make sure your model is assigned to a tenant
+
+3. **If using Ollama, check it's running:**
+   ```bash
+   ollama list
+   ```
+   - If you see "command not found", [install Ollama first](Ollama-Setup)
+   - If you see your models listed, Ollama is working
+
+---
+
+## "How do I see what's happening behind the scenes?"
+
+If something isn't working and you want to see the error messages:
+
+1. Open Terminal
+2. Go to your GT AI OS folder:
+   ```bash
+   cd ~/Desktop/gt-ai-os-community
+   ```
+3. View the logs:
+   ```bash
+   docker compose logs -f
+   ```
+4. To stop viewing logs, press `Ctrl+C` (hold Control and press C)
+
+**Tip:** To see logs for just one service:
+```bash
+docker compose logs -f tenant-backend
+```
+
+---
+
+## "I want to start completely fresh (delete everything)"
+
+**Warning:** This will delete ALL your data, including users, agents, and conversations.
+
+1. Open Terminal
+2. Go to your GT AI OS folder:
+   ```bash
+   cd ~/Desktop/gt-ai-os-community
+   ```
+3. Stop and remove everything:
+   ```bash
+   docker compose down -v
+   ```
+4. Run the installer again:
+   - **Ubuntu:** `./installers/install-gt2-ubuntu.sh`
+   - **DGX:** `sudo ./installers/install-gt2-dgx.sh`
+   - **macOS:** `./installers/install-gt2-mac.sh`
+
+---
+
+## "Nothing above helped - I need more support"
+
+1. **Check GitHub Issues:** Someone might have had the same problem:
+   https://github.com/GT-Edge-AI-Internal/gt-ai-os-community/issues
+
+2. **Open a new issue:** Describe your problem and include:
+   - What you were trying to do
+   - What error message you saw
+   - What computer you're using (Mac, Ubuntu, DGX)
+   - The output of `docker compose logs` (last 50 lines)