docs: Add placeholder metadata deployment guide

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

docs/PLACEHOLDER_METADATA_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,262 @@
+# Placeholder Metadata System - Deployment Guide
+
+**Status:** ✅ Code deployed to develop branch
+**Auto-Deploy:** Gitea runner should deploy to dev.mitai.jinkendo.de automatically
+
+---
+
+## Deployment Status
+
+### ✅ Completed
+
+1. **Code committed to develop branch**
+   - Commit: `a04e7cc`
+   - 9 files changed, 3889 insertions(+)
+   - All new modules and documentation included
+
+2. **Pushed to Gitea**
+   - Remote: http://192.168.2.144:3000/Lars/mitai-jinkendo
+   - Branch: develop
+   - Auto-deploy should trigger
+
+---
+
+## Post-Deployment Steps
+
+### 1. Wait for Auto-Deploy
+
+The Gitea runner should automatically deploy to:
+- **URL:** https://dev.mitai.jinkendo.de
+- **Container:** bodytrack-dev (Port 3099/8099)
+
+Check deployment status:
+```bash
+# On Raspberry Pi
+cd /home/lars/docker/bodytrack-dev
+docker compose logs -f backend --tail=100
+```
+
+### 2. Generate Catalog Files (Manual)
+
+Once deployed, SSH into the Raspberry Pi and run:
+
+```bash
+# SSH to Pi
+ssh lars@192.168.2.49
+
+# Navigate to container directory
+cd /home/lars/docker/bodytrack-dev
+
+# Generate catalog files
+docker compose exec backend python /app/generate_placeholder_catalog.py
+
+# Verify generated files
+docker compose exec backend ls -lh /app/docs/PLACEHOLDER_*.md
+docker compose exec backend ls -lh /app/docs/PLACEHOLDER_*.json
+```
+
+**Expected output files:**
+- `/app/docs/PLACEHOLDER_CATALOG_EXTENDED.json`
+- `/app/docs/PLACEHOLDER_CATALOG_EXTENDED.md`
+- `/app/docs/PLACEHOLDER_GAP_REPORT.md`
+- `/app/docs/PLACEHOLDER_EXPORT_SPEC.md`
+
+### 3. Test Extended Export Endpoint
+
+```bash
+# Get auth token first
+TOKEN=$(curl -s -X POST https://dev.mitai.jinkendo.de/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"YOUR_EMAIL","password":"YOUR_PASSWORD"}' \
+  | jq -r '.token')
+
+# Test extended export
+curl -s -H "X-Auth-Token: $TOKEN" \
+  https://dev.mitai.jinkendo.de/api/prompts/placeholders/export-values-extended \
+  | jq '.metadata.summary'
+```
+
+**Expected response:**
+```json
+{
+  "total_placeholders": 116,
+  "available": 98,
+  "missing": 18,
+  "by_type": {
+    "atomic": 85,
+    "interpreted": 20,
+    "raw_data": 8,
+    "legacy_unknown": 3
+  },
+  "coverage": {
+    "fully_resolved": 75,
+    "partially_resolved": 30,
+    "unresolved": 11
+  }
+}
+```
+
+### 4. Run Tests (Optional)
+
+```bash
+cd /home/lars/docker/bodytrack-dev
+docker compose exec backend pytest /app/tests/test_placeholder_metadata.py -v
+```
+
+### 5. Commit Generated Files
+
+After catalog generation, commit the generated files:
+
+```bash
+# On development machine
+cd c:/Dev/mitai-jinkendo
+
+# Pull generated files from server (if generated on server)
+# Or generate locally if you have DB access
+
+git add docs/PLACEHOLDER_CATALOG_EXTENDED.*
+git add docs/PLACEHOLDER_GAP_REPORT.md
+git add docs/PLACEHOLDER_EXPORT_SPEC.md
+
+git commit -m "docs: Add generated placeholder catalog files
+
+Generated via generate_placeholder_catalog.py
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
+
+git push origin develop
+```
+
+---
+
+## Verification Checklist
+
+After deployment, verify:
+
+- [ ] Backend container is running on dev.mitai.jinkendo.de
+- [ ] Extended export endpoint responds: `/api/prompts/placeholders/export-values-extended`
+- [ ] Catalog files generated successfully
+- [ ] Tests pass (if run)
+- [ ] No errors in container logs
+- [ ] Generated files committed to git
+
+---
+
+## Rollback (If Needed)
+
+If issues occur:
+
+```bash
+# On Raspberry Pi
+cd /home/lars/docker/bodytrack-dev
+
+# Rollback to previous commit
+git checkout c21a624
+
+# Rebuild and restart
+docker compose build --no-cache backend
+docker compose up -d backend
+```
+
+---
+
+## Production Deployment (Later)
+
+When ready for production:
+
+1. **Merge develop → main:**
+   ```bash
+   git checkout main
+   git merge develop
+   git push origin main
+   ```
+
+2. **Auto-deploy triggers for production:**
+   - URL: https://mitai.jinkendo.de
+   - Container: bodytrack (Port 3002/8002)
+
+3. **Repeat catalog generation on production container**
+
+---
+
+## Troubleshooting
+
+### Issue: Auto-deploy not triggered
+
+**Check:**
+```bash
+# On Raspberry Pi
+systemctl status gitea-runner
+journalctl -u gitea-runner -f
+```
+
+**Manual deploy:**
+```bash
+cd /home/lars/docker/bodytrack-dev
+git pull
+docker compose build --no-cache backend
+docker compose up -d backend
+```
+
+### Issue: Catalog generation fails
+
+**Check database connection:**
+```bash
+docker compose exec backend python -c "from db import get_db; conn = get_db(); print('DB OK')"
+```
+
+**Check placeholder_resolver import:**
+```bash
+docker compose exec backend python -c "from placeholder_resolver import PLACEHOLDER_MAP; print(len(PLACEHOLDER_MAP))"
+```
+
+### Issue: Extended export returns 500
+
+**Check logs:**
+```bash
+docker compose logs backend --tail=50
+```
+
+**Common issues:**
+- Missing database connection
+- Import errors in new modules
+- Placeholder resolver errors
+
+---
+
+## Monitoring
+
+Monitor the deployment:
+
+```bash
+# Watch logs
+docker compose logs -f backend
+
+# Check API health
+curl https://dev.mitai.jinkendo.de/api/version
+
+# Check extended export
+curl -H "X-Auth-Token: $TOKEN" \
+  https://dev.mitai.jinkendo.de/api/prompts/placeholders/export-values-extended \
+  | jq '.metadata.summary'
+```
+
+---
+
+## Next Steps After Deployment
+
+1. Review gap report for unresolved fields
+2. Test placeholder usage in prompts
+3. Update prompts to use new placeholders (if any)
+4. Plan production deployment timeline
+5. Update CLAUDE.md with new endpoints
+
+---
+
+## Resources
+
+- **Gitea:** http://192.168.2.144:3000/Lars/mitai-jinkendo
+- **Dev Environment:** https://dev.mitai.jinkendo.de
+- **Commit:** a04e7cc
+- **Implementation Docs:** docs/PLACEHOLDER_METADATA_IMPLEMENTATION_SUMMARY.md
+- **Governance:** docs/PLACEHOLDER_GOVERNANCE.md