Fix HuggingFace model cache permission error

Issue: Models pre-downloaded during Docker build were not readable
by the non-root user that HuggingFace Spaces uses at runtime.

Error: [Errno 13] Permission denied: '/app/.cache/huggingface/models--facebook--bart-large-mnli'

Solution: Add chmod -R 777 /app/.cache after downloading models
to ensure the cache directory is readable by any user.

This fixes the repeated "Error analyzing submission" and "Error loading model"
errors that were occurring when analyzing submissions on HuggingFace Spaces.

Also added comprehensive deployment and setup documentation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Dockerfile

@@ -56,7 +56,8 @@ RUN python -c "from transformers import pipeline; \
     pipeline('zero-shot-classification', model='MoritzLaurer/DeBERTa-v3-base-mnli-fever-anli', device=-1); \
     print('Downloading DistilBART-MNLI...'); \
     pipeline('zero-shot-classification', model='valhalla/distilbart-mnli-12-3', device=-1); \
-    print('All models downloaded successfully')"
+    print('All models downloaded successfully')" \
+    && chmod -R 777 /app/.cache
 
 # Hugging Face Spaces uses port 7860
 EXPOSE 7860

PUSH_TO_HUGGINGFACE.md

@@ -0,0 +1,137 @@
+# How to Push to HuggingFace
+
+## The Issue
+
+Git push to HuggingFace isn't prompting for authentication because we're in a non-interactive environment. Here's how to authenticate properly:
+
+---
+
+## Solution: Use HuggingFace CLI to Login
+
+### Step 1: Login with HuggingFace CLI
+
+Run this command in your terminal:
+
+```bash
+huggingface-cli login
+```
+
+When prompted:
+- Enter your **new HuggingFace write token** (the one you created after revoking the old one)
+- The token should start with `hf_...`
+- Choose **Yes** when asked to add token as git credential
+
+This will:
+1. Store your HuggingFace token securely
+2. Configure git to use it for HuggingFace operations
+3. Enable pushing to your HuggingFace Space
+
+### Step 2: Push to HuggingFace
+
+After logging in, push your changes:
+
+```bash
+cd /home/thadillo/MyProjects/participatory_planner
+git push hf feature/sentence-level-categorization:main
+```
+
+This should now work without prompting!
+
+---
+
+## Alternative: Manually Add HuggingFace Credential
+
+If the CLI login doesn't work, you can manually add the credential:
+
+```bash
+# Add HuggingFace credential to git credentials file
+echo "https://thadillo:YOUR_NEW_HF_TOKEN@huggingface.co" >> ~/.git-credentials
+```
+
+Replace `YOUR_NEW_HF_TOKEN` with your actual HuggingFace token.
+
+Then push:
+```bash
+git push hf feature/sentence-level-categorization:main
+```
+
+---
+
+## Alternative: Use Git with Token in URL (One-time)
+
+If you prefer a one-time push without storing credentials:
+
+```bash
+cd /home/thadillo/MyProjects/participatory_planner
+
+# Push with token embedded (replace YOUR_TOKEN)
+git push https://thadillo:YOUR_NEW_HF_TOKEN@huggingface.co/spaces/thadillo/participatory-planner feature/sentence-level-categorization:main
+```
+
+**Warning**: This doesn't store the credential, so you'll need to do this every time.
+
+---
+
+## Verify the Push
+
+After pushing successfully, verify:
+
+1. **Check HuggingFace Space**: https://huggingface.co/spaces/thadillo/participatory-planner
+2. **Check Build Logs**: https://huggingface.co/spaces/thadillo/participatory-planner/logs
+3. **Verify Files Updated**: The commit should show in the Space's Files tab
+
+---
+
+## What Happens Next
+
+Once pushed, HuggingFace will:
+1. Automatically rebuild your Space
+2. Apply all the security fixes
+3. Fix the deployment errors (TRANSFORMERS_CACHE, matplotlib, SQLite)
+
+**Don't forget**: You still need to set the HuggingFace Spaces secrets (FLASK_SECRET_KEY and ADMIN_TOKEN) as described in SETUP_INSTRUCTIONS.md!
+
+---
+
+## Quick Commands Summary
+
+```bash
+# Option 1: Login with HuggingFace CLI (recommended)
+huggingface-cli login
+git push hf feature/sentence-level-categorization:main
+
+# Option 2: Manual credential file edit
+echo "https://thadillo:YOUR_HF_TOKEN@huggingface.co" >> ~/.git-credentials
+git push hf feature/sentence-level-categorization:main
+
+# Option 3: One-time push with token
+git push https://thadillo:YOUR_HF_TOKEN@huggingface.co/spaces/thadillo/participatory-planner feature/sentence-level-categorization:main
+```
+
+---
+
+## Troubleshooting
+
+### Error: "Authentication failed"
+- Double-check your HuggingFace token is correct
+- Ensure it's a **write** token (not read-only)
+- Verify the token hasn't expired
+
+### Error: "could not read Username"
+- This means git isn't getting credentials properly
+- Use `huggingface-cli login` to fix this
+
+### Error: "remote rejected"
+- Check you have write access to the Space
+- Verify the Space name is correct: `thadillo/participatory-planner`
+
+---
+
+## Current Status
+
+- ✅ All changes committed to git
+- ✅ Pushed to GitHub successfully
+- ⏳ **Waiting for you to push to HuggingFace**
+- ⏳ Waiting for HuggingFace Spaces secrets to be set
+
+Follow the steps above to complete the deployment!

SETUP_INSTRUCTIONS.md

@@ -0,0 +1,270 @@
+# Security Setup Instructions
+
+## Summary
+
+All security improvements have been successfully committed and pushed to GitHub. Follow the instructions below to complete the deployment to HuggingFace and set up your environment variables.
+
+## What Was Fixed
+
+### Security Improvements ✅
+- Removed hardcoded ADMIN123 token (now environment-based with auto-generation)
+- Rotated Flask secret key with fail-fast validation
+- Added rate limiting to authentication endpoints
+- Removed exposed HuggingFace token from git config
+- Created comprehensive SECURITY.md documentation
+
+### HuggingFace Deployment Fixes ✅
+- Fixed TRANSFORMERS_CACHE deprecation warning
+- Resolved matplotlib permission errors
+- Improved SQLite database locking issues
+- Fixed sentence text display in PDF exports
+
+---
+
+## Step 1: Push to HuggingFace
+
+Since you revoked the old HuggingFace token, you need to authenticate with your new token:
+
+```bash
+cd /home/thadillo/MyProjects/participatory_planner
+
+# Push to HuggingFace (you'll be prompted for credentials)
+git push hf feature/sentence-level-categorization:main
+```
+
+When prompted:
+- **Username**: `thadillo`
+- **Password**: Enter your **NEW HuggingFace write token** (starts with `hf_...`)
+
+The credentials will be stored in git credential helper for future pushes.
+
+---
+
+## Step 2: Configure HuggingFace Spaces Secrets
+
+Go to your HuggingFace Space settings and add these **Repository Secrets**:
+
+https://huggingface.co/spaces/thadillo/participatory-planner/settings
+
+### Required Secrets:
+
+1. **FLASK_SECRET_KEY** (Critical - for session security)
+   ```
+   Generate a new one with:
+   python -c "import secrets; print(secrets.token_hex(32))"
+
+   Example output (DO NOT USE THIS - generate your own):
+   c5eafdcbd348d3176bf1fcf52d90357575f7bc1986b7baeb67bb9d140f401881
+   ```
+
+2. **ADMIN_TOKEN** (Critical - for admin access)
+   ```
+   Generate a new one with:
+   python -c "import secrets; print(secrets.token_urlsafe(16))"
+
+   Example output (DO NOT USE THIS - generate your own):
+   xulmKoajFS07akF9Eos9Tg
+   ```
+
+   **SAVE THIS TOKEN SECURELY** - You'll need it to log in to the admin panel!
+
+### How to Add Secrets in HuggingFace:
+
+1. Go to your Space: https://huggingface.co/spaces/thadillo/participatory-planner
+2. Click **Settings** tab
+3. Scroll to **Repository Secrets** section
+4. Click **New Secret**
+5. Add each secret:
+   - Name: `FLASK_SECRET_KEY`
+   - Value: (paste the generated secret key)
+   - Click **Add**
+6. Repeat for `ADMIN_TOKEN`
+
+---
+
+## Step 3: Configure Local Development Environment
+
+Update your local `.env` file with the **SAME** values you set in HuggingFace:
+
+```bash
+cd /home/thadillo/MyProjects/participatory_planner
+
+# Edit your .env file
+nano .env
+```
+
+Your `.env` file should contain:
+
+```env
+# Flask Configuration
+FLASK_SECRET_KEY=<PASTE THE SAME VALUE YOU USED IN HUGGINGFACE>
+FLASK_ENV=development
+
+# Model Configuration
+MODELS_DIR=models/finetuned
+CUDA_VISIBLE_DEVICES=-1
+
+# Admin Token (must match HuggingFace secret)
+ADMIN_TOKEN=<PASTE THE SAME VALUE YOU USED IN HUGGINGFACE>
+```
+
+**Important**: Use the **EXACT SAME** values for `FLASK_SECRET_KEY` and `ADMIN_TOKEN` that you set in HuggingFace. This ensures your local environment matches production.
+
+---
+
+## Step 4: Verify Local Setup
+
+Test that your local environment works correctly:
+
+```bash
+cd /home/thadillo/MyProjects/participatory_planner
+
+# Start the application
+./start.sh
+```
+
+You should see output like:
+```
+🔐 Admin token: Check startup logs or set ADMIN_TOKEN in .env
+🚀 Starting application...
+```
+
+If you didn't set `ADMIN_TOKEN` in `.env`, a random token will be generated and displayed **ONCE** in the logs. Save it immediately!
+
+---
+
+## Step 5: Test Admin Access
+
+### Local Testing:
+1. Start the application: `./start.sh`
+2. Go to: http://localhost:5000/generate
+3. Generate a new token using your **ADMIN_TOKEN**
+4. Use the generated token to test the application
+
+### HuggingFace Testing:
+1. Wait for HuggingFace to rebuild (after pushing changes)
+2. Go to: https://thadillo-participatory-planner.hf.space/generate
+3. Generate a new token using your **ADMIN_TOKEN**
+4. Verify the application works without the previous errors
+
+---
+
+## Step 6: Verify HuggingFace Deployment
+
+After pushing to HuggingFace, monitor the build logs:
+
+https://huggingface.co/spaces/thadillo/participatory-planner/logs
+
+**Check for these confirmations:**
+1. ✅ No TRANSFORMERS_CACHE deprecation warning
+2. ✅ No matplotlib permission errors
+3. ✅ No SQLite database locking errors
+4. ✅ Application starts successfully
+
+---
+
+## Security Best Practices Going Forward
+
+### DO:
+✅ Keep `.env` file local and never commit it to git
+✅ Use different secrets for development and production
+✅ Rotate secrets periodically (every 3-6 months)
+✅ Store production secrets only in HuggingFace Spaces secrets
+✅ Use strong, randomly generated tokens (via `secrets` module)
+
+### DON'T:
+❌ Never commit `.env` to git
+❌ Never hardcode secrets in code
+❌ Never share your ADMIN_TOKEN publicly
+❌ Never use simple passwords like "ADMIN123"
+❌ Never include tokens in git remote URLs
+
+---
+
+## Quick Reference Commands
+
+### Generate Flask Secret Key:
+```bash
+python -c "import secrets; print(secrets.token_hex(32))"
+```
+
+### Generate Admin Token:
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(16))"
+```
+
+### Push to HuggingFace:
+```bash
+git push hf feature/sentence-level-categorization:main
+```
+
+### Start Local Server:
+```bash
+./start.sh
+```
+
+### View HuggingFace Logs:
+https://huggingface.co/spaces/thadillo/participatory-planner/logs
+
+### View HuggingFace Settings:
+https://huggingface.co/spaces/thadillo/participatory-planner/settings
+
+---
+
+## Troubleshooting
+
+### If HuggingFace deployment fails:
+1. Check the build logs for error messages
+2. Verify all secrets are set correctly in HuggingFace settings
+3. Ensure `FLASK_SECRET_KEY` and `ADMIN_TOKEN` are set
+
+### If you get "database is locked" errors:
+- The new retry logic should handle this automatically
+- If it persists, check HuggingFace logs for concurrent request issues
+
+### If you forget your ADMIN_TOKEN:
+1. Generate a new one: `python -c "import secrets; print(secrets.token_urlsafe(16))"`
+2. Update it in HuggingFace Spaces secrets
+3. Update it in your local `.env` file
+4. Restart the application
+
+### If authentication fails:
+- Ensure you're using the correct ADMIN_TOKEN
+- Check that rate limiting hasn't blocked you (wait 1 hour)
+- Verify the token in HuggingFace secrets matches your local `.env`
+
+---
+
+## Next Steps
+
+1. **Immediate**: Push to HuggingFace using the command above
+2. **Immediate**: Set up HuggingFace Spaces secrets (FLASK_SECRET_KEY, ADMIN_TOKEN)
+3. **Immediate**: Update your local `.env` file
+4. **Soon**: Test the application on HuggingFace to verify all errors are resolved
+5. **Optional**: Consider merging `feature/sentence-level-categorization` to `main` branch
+
+---
+
+## Files Modified
+
+All changes have been committed to git. Here's what was changed:
+
+- [app/__init__.py](app/__init__.py) - Secure token generation, secret key validation, rate limiter
+- [app/routes/auth.py](app/routes/auth.py) - Rate limiting on login/generate endpoints
+- [app/routes/admin.py](app/routes/admin.py) - Removed hardcoded ADMIN123 references
+- [requirements.txt](requirements.txt) - Added Flask-Limiter
+- [.env.example](.env.example) - Updated with new structure
+- [Dockerfile](Dockerfile) - Fixed HuggingFace deployment issues
+- [SECURITY.md](SECURITY.md) - New comprehensive security documentation
+- Multiple markdown files - Documentation cleanup
+
+---
+
+## Support
+
+For questions or issues:
+- Review [SECURITY.md](SECURITY.md) for detailed security information
+- Check HuggingFace build logs for deployment errors
+- Verify environment variables are set correctly
+
+**Remember**: Save your ADMIN_TOKEN securely - it's shown only once when auto-generated!