portfolio/n8n-workflows/QUICK-REFERENCE.md

# 🎯 Telegram CMS Bot - Quick Reference

## 📱 Commands Cheat Sheet

### Core Commands
```
/start                          # Dashboard with stats
/list projects                  # Show all projects
/list books                     # Show all book reviews
/search <term>                  # Search across all content
/stats                          # Detailed analytics
```

### Item Management
```
/preview<ID>                    # View item details (both languages)
/publish<ID>                    # Publish item (auto-detect type)
/delete<ID>                     # Delete item (auto-detect type)
/deletereview<ID>               # Remove review translations only
```

### Legacy Commands (still supported)
```
/publishproject<ID>             # Publish specific project
/publishbook<ID>                # Publish specific book
/deleteproject<ID>              # Delete specific project
/deletebook<ID>                 # Delete specific book
```

### AI Review Creation
```
.review <HARDCOVER_ID> <RATING> <YOUR_THOUGHTS>
```

**Example:**
```
.review 12345 5 Absolutely loved this book! The character development was outstanding and the plot kept me engaged throughout. Highly recommend for anyone interested in fantasy literature.
```

**Result:**
- Creates EN + DE reviews via AI
- Sets rating (1-5 stars)
- Saves as draft in CMS
- Provides publish/delete buttons

---

## 🎨 Response Format

All responses use Markdown formatting with emojis:

### Dashboard
```
🎯 DK0 Portfolio CMS

📊 Stats:
• Draft Projects: 3
• Draft Reviews: 2

💡 Quick Actions:
/list projects - View all projects
...
```

### List View
```
📋 PROJECTS (Page 1)

1. Next.js Portfolio
   Category: Web Development
   Status: draft
   /preview42 | /publish42 | /delete42
```

### Preview
```
👁️ Preview #42

📁 Type: Project
🔖 Slug: nextjs-portfolio
🏷️ Category: Web Development
📊 Status: draft

🇬🇧 EN:
Title: Next.js Portfolio
Description: Modern portfolio built with...

🇩🇪 DE:
Title: Next.js Portfolio
Description: Modernes Portfolio erstellt mit...

Actions:
/publish42 - Publish
/delete42 - Delete
```

---

## 🔍 Auto-Detection

The workflow automatically detects item types:

| Command | Behavior |
|---------|----------|
| `/preview42` | Checks projects → checks books |
| `/publish42` | Checks projects → checks books |
| `/delete42` | Checks projects → checks books |

No need to specify collection type!

---

## 💡 Tips & Tricks

1. **Quick Publishing:**
   ```
   /list projects    # Get item ID
   /preview42        # Review content
   /publish42        # Publish
   ```

2. **Bulk Review:**
   ```
   /list books       # See all books
   /preview*         # Check each one
   /publish*         # Publish ready ones
   ```

3. **Search Before Create:**
   ```
   /search "react"   # Check existing content
   # Then create new if needed
   ```

4. **AI Review Workflow:**
   ```
   .review 12345 5 My thoughts here
   # AI generates EN + DE versions
   /preview<ID>      # Review AI output
   /publish<ID>      # Publish if good
   /deletereview<ID> # Remove & retry if bad
   ```

---

## ⚠️ Common Issues

### ❌ "Item not found"
- Verify ID is correct
- Check if item exists in CMS
- Try /search to find correct ID

### ❌ "Error loading dashboard"
- Directus might be down
- Check network connection
- Try again in 30 seconds

### ❌ AI review fails
- Verify Hardcover ID exists
- Check rating is 1-5
- Ensure you provided text

### ❌ No response from bot
- Bot might be restarting
- Check n8n workflow is active
- Wait 1 minute and retry

---

## 📊 Status Values

| Status | Meaning | Action |
|--------|---------|--------|
| `draft` | Not visible on site | Use `/publish` |
| `published` | Live on dk0.dev | ✅ Done |
| `archived` | Hidden but kept | Use `/delete` to remove |

---

## 🎯 Workflow Logic

```mermaid
graph TD
    A[Telegram Message] --> B[Parse Command]
    B --> C{Command Type?}
    C -->|/start| D[Dashboard]
    C -->|/list| E[List Handler]
    C -->|/search| F[Search Handler]
    C -->|/stats| G[Stats Handler]
    C -->|/preview| H[Preview Handler]
    C -->|/publish| I[Publish Handler]
    C -->|/delete| J[Delete Handler]
    C -->|/deletereview| K[Delete Review]
    C -->|.review| L[Create Review AI]
    C -->|unknown| M[Help Message]
    D --> N[Send Message]
    E --> N
    F --> N
    G --> N
    H --> N
    I --> N
    J --> N
    K --> N
    L --> N
    M --> N
```

---

## 🚀 Performance

- **Dashboard:** ~1-2s
- **List:** ~1-2s (5 items)
- **Search:** ~1-2s
- **Preview:** ~1s
- **Publish/Delete:** ~1s
- **AI Review:** ~3-5s

---

## 📝 Examples

### Complete Workflow Example

```bash
# Step 1: Check what's available
/start

# Step 2: List projects
/list projects

# Step 3: Preview one
/preview42

# Step 4: Looks good? Publish!
/publish42

# Step 5: Create a book review
.review 12345 5 Amazing book about TypeScript!

# Step 6: Check the generated review
/preview<ID>

# Step 7: Publish it
/publish<ID>

# Step 8: Get overall stats
/stats
```

---

## 🔗 Integration Points

| System | Purpose | Endpoint |
|--------|---------|----------|
| Directus | CMS data | https://cms.dk0.dev |
| OpenRouter | AI reviews | https://openrouter.ai |
| Telegram | Bot interface | DK0_Server |
| Portfolio | Live site | https://dk0.dev |

---

## 📞 Support

**Problems?** Check:
1. n8n workflow logs
2. Directus API status
3. Telegram bot status
4. This quick reference

**Still stuck?** Contact Dennis Konkol

---

**Last Updated:** 2025-01-21  
**Version:** 1.0.0  
**Status:** ✅ Production Ready