feat: Implement versioning documentation

docs/versioning/TROUBLESHOOTING.md

@@ -0,0 +1,67 @@
+# Troubleshooting Guide
+
+## Versions Not Being Created
+
+**Symptoms:** Entity updates don't create versions
+
+**Solutions:**
+1. Check if triggers are enabled: `SELECT * FROM pg_trigger WHERE tgname LIKE '%version%';`
+2. Verify session variables are set in edge function
+3. Check trigger function logs in Supabase dashboard
+4. Ensure entity table has trigger attached
+
+## "Cannot read versions" Error
+
+**Symptoms:** Frontend can't fetch versions
+
+**Solutions:**
+1. Check RLS policies on version tables
+2. Verify user authentication (is `auth.uid()` valid?)
+3. Check entity exists
+4. Inspect browser console for specific error
+
+## Version History Not Showing in UI
+
+**Symptoms:** Component renders but no versions display
+
+**Solutions:**
+1. Verify `useEntityVersions` hook is called correctly
+2. Check entity ID is correct
+3. Inspect network tab for failed queries
+4. Check if versions exist in database
+
+## Rollback Fails
+
+**Symptoms:** "Permission denied" or rollback doesn't work
+
+**Solutions:**
+1. Verify user has moderator role: `SELECT has_role(auth.uid(), 'moderator')`
+2. Check target version exists
+3. Ensure entity hasn't been deleted
+4. Check MFA requirement (`has_aal2()`)
+
+## Attribution Issues
+
+**Symptoms:** Versions attributed to moderator instead of submitter
+
+**Solutions:**
+1. Verify edge function sets `app.current_user_id` to `submission.user_id`
+2. Check session variables before entity update
+3. Review trigger function logic
+
+## Performance Issues
+
+**Symptoms:** Slow version queries
+
+**Solutions:**
+1. Check indexes exist on version tables
+2. Run `cleanup_old_versions()` to reduce table size
+3. Implement pagination for large version lists
+4. Use `is_current = true` filter when only latest version needed
+
+## Need Help?
+
+- Review [ARCHITECTURE.md](./ARCHITECTURE.md) for system design
+- Check [SCHEMA.md](./SCHEMA.md) for database structure
+- See [FRONTEND.md](./FRONTEND.md) for React integration
+- Consult [MODERATION.md](./MODERATION.md) for workflow issues