Initial commit

docs/TROUBLESHOOTING.md

@@ -0,0 +1,564 @@
+# Troubleshooting Guide
+
+**For:** Wiki-GhostGuild Content Contributors
+
+Common issues and solutions.
+
+---
+
+## Obsidian Issues
+
+### Obsidian Won't Open Vault
+
+**Symptom:** "Vault not found" or error when opening folder
+
+**Solutions:**
+
+1. **Check path:** Make sure you're opening the exact right folder
+   ```bash
+   # Should be this:
+   /path/to/wiki-ghostguild/content/articles/
+
+   # Not this:
+   /path/to/wiki-ghostguild/  # Parent folder
+   /path/to/wiki-ghostguild/content/  # Wrong subfolder
+   ```
+
+2. **Full path issues:** On Mac, use full path starting with `/Users/`
+   ```
+   /Users/yourname/Sites/wiki-ghostguild/content/articles/
+   ```
+
+3. **Permissions:** Make sure you have read/write access
+   ```bash
+   ls -ld /path/to/wiki-ghostguild/content/articles/
+   # Should show: drwxrwxr-x (or similar with r+w)
+   ```
+
+4. **Restart Obsidian:** Close completely and reopen
+
+---
+
+### Wikilinks Showing as Red (Broken)
+
+**Symptom:** `[[Page Name]]` appears in red in Obsidian
+
+**Causes & Solutions:**
+
+1. **Typo in page name**
+   ```
+   ❌ [[Communication Norms]] - Missing full title
+   ✅ [[Communication Norms Document for Game Studios]]
+   ```
+   → Links must match article titles exactly
+
+2. **Title in frontmatter doesn't match**
+   ```yaml
+   # In article file:
+   ---
+   title: "Communication Norms Document for Game Studios"
+   ---
+
+   # Then this works:
+   [[Communication Norms Document for Game Studios]]
+
+   # But this doesn't:
+   [[Communication Norms]] # Partial match doesn't work
+   ```
+
+3. **Cache issue**
+   - Close Obsidian completely
+   - Wait 10 seconds
+   - Reopen
+   - Wikilink should show as blue now
+
+4. **Check article exists**
+   - Open Graph view: Left sidebar → "Graph" tab
+   - Search for the article title
+   - If not there, article file is missing or title is wrong
+
+---
+
+### Images Not Saving
+
+**Symptom:** Paste image, nothing appears or goes to wrong location
+
+**Solutions:**
+
+1. **Check attachment folder setting**
+   - Settings → Files & Links
+   - "Attachment folder path" should be: `../../public/img`
+   - If different, change it back
+
+2. **Folder doesn't exist**
+   ```bash
+   # Check:
+   ls /path/to/wiki-ghostguild/public/img/
+
+   # If not there, create:
+   mkdir -p /path/to/wiki-ghostguild/public/img/
+   ```
+
+3. **Try again**
+   - Paste image: `Cmd+V` (Mac) or `Ctrl+V`
+   - Should prompt for filename
+   - Edit if needed and confirm
+   - Image should appear and be saved to `/public/img/`
+
+4. **Check permissions**
+   ```bash
+   ls -ld /path/to/wiki-ghostguild/public/img/
+   # Should be writable (w flag)
+   ```
+
+5. **Restart Obsidian**
+   - Close completely
+   - Reopen vault
+   - Try pasting again
+
+---
+
+### Obsidian Git Not Working
+
+**Symptom:** Obsidian Git plugin not appearing or not committing
+
+**Solutions:**
+
+1. **Plugin not enabled**
+   - Settings → Community plugins
+   - Search "Obsidian Git"
+   - Toggle ON if disabled
+
+2. **Restricted mode**
+   - Settings → Community plugins
+   - If "Restricted mode ON" shows, click toggle
+   - Enable plugins
+   - Refresh
+
+3. **Git not installed**
+   ```bash
+   # Check if git is available:
+   which git
+   # Should show: /usr/bin/git or similar
+
+   # If not, install:
+   # Mac: brew install git
+   # Windows: Download from git-scm.com
+   ```
+
+4. **Not in git repository**
+   ```bash
+   # Check:
+   cd /path/to/wiki-ghostguild
+   git status
+
+   # Should show branch info, not "fatal: not a git repository"
+   ```
+
+5. **Configure git identity**
+   ```bash
+   git config user.name "Your Name"
+   git config user.email "your@email.com"
+   ```
+
+6. **Reload plugin**
+   - Settings → Community plugins → Obsidian Git → Reload
+
+---
+
+## Git Issues
+
+### Can't Push (Remote Rejection)
+
+**Symptom:** "Permission denied" or "rejected" when pushing
+
+**Causes:**
+1. Not authenticated to Forgejo
+2. Remote URL is wrong
+3. Branch is wrong
+
+**Solutions:**
+
+1. **Check remote URL**
+   ```bash
+   cd wiki-ghostguild
+   git remote -v
+   # Should show:
+   # origin https://your-forgejo.com/org/wiki-ghostguild.git
+   ```
+
+2. **Fix if wrong**
+   ```bash
+   git remote set-url origin https://your-forgejo.com/org/wiki-ghostguild.git
+   git push
+   ```
+
+3. **Authenticate to Forgejo**
+   - Generate personal token (Forgejo settings)
+   - Use token as password when git prompts
+   - Or set up SSH key
+
+4. **Check branch**
+   ```bash
+   git branch
+   # Should be on 'main' (or whatever default branch)
+   ```
+
+---
+
+### Merge Conflict
+
+**Symptom:** "CONFLICT" in Obsidian Git or error when pulling
+
+**Solutions:**
+
+1. **See conflict file**
+   - Look for `conflict-files-obsidian-git.md`
+   - Or use `git status` to see conflicted files
+
+2. **Resolve conflict**
+   ```markdown
+   # Find conflict markers:
+   <<<<<<< HEAD
+   Your version (what you wrote)
+   =======
+   Their version (what they wrote)
+   >>>>>>> main
+
+   # Delete one section and keep what's correct
+   # Or merge both if both are needed
+   # Remove the markers: <<<<, ====, >>>>
+   ```
+
+3. **After resolving**
+   ```bash
+   # Mark as resolved
+   git add file-name.md
+
+   # Commit the resolution
+   git commit -m "Resolve conflict in file-name.md"
+
+   # Push
+   git push
+   ```
+
+4. **Prevent future conflicts**
+   - **Pull before editing:** Start work each day with `git pull`
+   - **Work on different files:** If both editing, use different articles
+   - **Push frequently:** Don't let changes pile up
+
+---
+
+## Building Issues
+
+### Build Fails: "error TS..."
+
+**Symptom:** `npm run generate` shows TypeScript errors
+
+**Solutions:**
+
+1. **Check file syntax**
+   ```bash
+   # Errors show file path and line number
+   # Fix the TypeScript error mentioned
+   ```
+
+2. **Clear cache and try again**
+   ```bash
+   rm -rf .nuxt .output
+   npm run generate
+   ```
+
+3. **Check dependencies**
+   ```bash
+   npm install
+   npm run generate
+   ```
+
+---
+
+### Build Fails: "Invalid frontmatter"
+
+**Symptom:** Build error about article YAML
+
+**Solutions:**
+
+1. **Check YAML syntax**
+   ```yaml
+   # ✅ Correct syntax
+   ---
+   title: "My Article"
+   tags:
+     - tag1
+     - tag2
+   ---
+
+   # ❌ Common errors
+   tags: tag1, tag2  # Wrong - should be array with brackets
+   title: My Article  # Missing quotes (usually ok, but can cause issues)
+   author "Name"  # Missing colon
+   ```
+
+2. **Validate YAML online**
+   - Copy frontmatter to https://www.yamllint.com
+   - Fix any errors it shows
+
+3. **Check required fields**
+   ```yaml
+   # Minimum required:
+   ---
+   title: "Article Title"
+   ---
+
+   # All other fields are optional
+   ```
+
+---
+
+### Build Fails: "No such file"
+
+**Symptom:** "Cannot find module" or "ENOENT" error
+
+**Solutions:**
+
+1. **Check file exists**
+   ```bash
+   ls app/server/plugins/wikilink-transform.ts
+   ls content.config.ts
+   ```
+
+2. **Check for typos in imports**
+   - Look at error message for exact path
+   - Make sure it matches actual file
+
+3. **Reinstall dependencies**
+   ```bash
+   rm -rf node_modules package-lock.json
+   npm install
+   npm run generate
+   ```
+
+---
+
+### Dev Server Slow / Hot Reload Not Working
+
+**Symptom:** Changes take a long time to appear, or don't appear
+
+**Solutions:**
+
+1. **Restart dev server**
+   ```bash
+   # Stop: Ctrl+C
+   npm run dev
+   ```
+
+2. **Clear cache**
+   ```bash
+   rm -rf .nuxt
+   npm run dev
+   ```
+
+3. **Port conflict**
+   ```bash
+   # If port 3000 taken:
+   npm run dev -- -p 3001
+   # Then visit: http://localhost:3001
+   ```
+
+4. **File too large**
+   - If a single article is very large (>10,000 lines)
+   - It may reload slowly
+   - Consider splitting into multiple articles
+
+---
+
+## Deployment Issues
+
+### Website Shows Old Content
+
+**Symptom:** Changes pushed but don't appear on live site
+
+**Causes:**
+1. Build not triggered
+2. Cache not cleared
+3. Deployment not complete
+
+**Solutions:**
+
+1. **Force rebuild on server**
+   ```bash
+   cd wiki-ghostguild
+   git pull
+   npm run generate
+   # Restart web server
+   ```
+
+2. **Clear server cache**
+   - Check hosting provider docs
+   - Usually: Clear CDN cache or restart server
+
+3. **Check deployment status**
+   - Look at CI/CD pipeline status
+   - Check if build completed successfully
+
+---
+
+## Networking Issues
+
+### Can't Clone Repository
+
+**Symptom:** "Permission denied" or authentication fails
+
+**Solutions:**
+
+1. **Set up SSH key (recommended)**
+   ```bash
+   ssh-keygen -t ed25519 -C "your@email.com"
+   # Add public key to Forgejo settings
+   git clone git@your-forgejo.com:org/wiki-ghostguild.git
+   ```
+
+2. **Or use HTTPS with token**
+   ```bash
+   # Generate personal token in Forgejo
+   git clone https://your-forgejo.com/org/wiki-ghostguild.git
+   # Use token as password when prompted
+   ```
+
+3. **Internet connection**
+   - Check you have internet
+   - Try `ping google.com`
+
+---
+
+### Port Already in Use
+
+**Symptom:** `npm run dev` fails with "port already in use"
+
+**Solutions:**
+
+```bash
+# Find what's using the port
+ps aux | grep nuxt
+ps aux | grep node
+
+# Kill the process (replace 12345 with PID)
+kill -9 12345
+
+# Or use different port
+npm run dev -- -p 3001
+```
+
+---
+
+## Article Issues
+
+### Frontmatter Missing After Editing
+
+**Symptom:** Content looks corrupted in Obsidian
+
+**Solutions:**
+
+1. **Check file**
+   ```bash
+   head -20 content/articles/article-name.md
+   # Should start with:
+   # ---
+   # title: ...
+   ```
+
+2. **Recover from git**
+   ```bash
+   git checkout content/articles/article-name.md
+   # Reverts to last committed version
+   ```
+
+3. **Check git status**
+   ```bash
+   git status
+   # Should show what's changed
+   ```
+
+---
+
+### Article Not Appearing in List
+
+**Symptom:** Article is in /content/articles/ but doesn't show up
+
+**Solutions:**
+
+1. **Check frontmatter**
+   ```yaml
+   ---
+   title: "Article Title"
+   published: true  # Must be true or missing (default true)
+   ---
+   ```
+
+2. **Check accessibility**
+   ```yaml
+   # If accessLevel is wrong, won't show:
+   accessLevel: "member"  # User must be logged in
+
+   # Try public for testing:
+   accessLevel: "public"
+   ```
+
+3. **Check file saved**
+   ```bash
+   git status
+   # If file shows modified, haven't committed yet
+   ```
+
+4. **Rebuild**
+   ```bash
+   npm run generate
+   npm run preview
+   # Check at http://localhost:3000
+   ```
+
+---
+
+## Getting More Help
+
+If not in this guide:
+
+1. **Check the docs:**
+   - `OBSIDIAN_SETUP_GUIDE.md` - User guide
+   - `TECHNICAL_ARCHITECTURE.md` - How it works
+
+2. **Check error message:**
+   - Copy exact error
+   - Search online
+   - Try suggestion from error
+
+3. **Check logs:**
+   ```bash
+   npm run dev 2>&1 | tee build.log
+   # Look for warnings/errors
+   # Look for file paths that don't exist
+   ```
+
+4. **Ask team:**
+   - Slack/Discord
+   - Comment in pull request
+   - Email team lead
+
+---
+
+**Remember:** Most issues are related to:
+- ❌ Wrong folder path
+- ❌ Missing git configuration
+- ❌ Typo in article title
+- ❌ Stale cache
+
+99% of the time, one of these fixes it:
+1. `rm -rf .nuxt && npm run dev`
+2. `git pull`
+3. `npm install`
+4. Restart Obsidian
+5. Restart terminal
+
+---
+
+**Last Updated:** November 2025