# Broccolini Bot – Quick Start Guide

Get started with Broccolini Bot in 5 minutes! Run all commands from the repo root. Ensure `.env` exists in the repo root (copy from `.env.example`).

**Test env:** To try changes safely, use `.env.test` (copy from `.env.test.example`) and run `npm run start:test`. See [ENV_AND_SECURITY.md](./ENV_AND_SECURITY.md). **Agents:** do not modify `.env` without explicit user confirmation; prefer changing `.env.test` first.

## 1. Restart Your Bot

```bash
npm start
```

The bot will automatically:
- Use MongoDB collections (Tag, CloseRequest, etc.) as needed
- Register all new slash commands
- Start background jobs (auto-close, auto-unclaim, reminders)

## 2. Create Your First Saved Response

```
/response create name:welcome content:Welcome to support, {ticket.user}! We'll help you with {ticket.subject}.
```

Then use it:
```
/response send name:welcome
```

Use `/tag` in a ticket channel to set the ticket category (dropdown: Server Down, Billing, Mod Help, etc.). The bot posts: *Your ticket has been categorized as [Emoji][Tag][Emoji].*

## 3. Set Up a Ticket Panel

```
/panel #support-tickets type:both title:Need Help? description:Click below to open a ticket!
```

Use `type` to choose **thread**, **category**, or **both**. Users click the button → Fill out modal → Ticket created automatically!

## 4. Try the New Commands

### User Management
```
/add @user           # Add someone to current ticket
/remove @user        # Remove someone from ticket
```

### Ticket Actions
```
/transfer @staff     # Transfer to another staff member
/move #category      # Move to different category
/priority [level]    # Set priority: posts upgraded/downgraded/normal message; email sent when set to high
/topic Important!    # Set channel topic
/escalate [reason] [tier]  # Escalate to tier 2 or 3 (or use Escalate button)
/deescalate         # De-escalate one step
/force-close        # Close without confirmation
```

### Close Confirmation
Click "Close Ticket" button → Get confirmation prompt → Confirm or cancel

## 5. Configure New Options

Edit your `.env`:

```env
# Enable auto-unclaim after 24 hours of inactivity
AUTO_UNCLAIM_ENABLED=true
AUTO_UNCLAIM_AFTER_HOURS=24

# Allow staff to claim already-claimed tickets
ALLOW_CLAIM_OVERWRITE=true

# Use threads instead of channels (future)
USE_THREADS=false
```

**Restart the bot** after changing `.env`; slash commands may need re-registration (restart the bot).

## 6. Use Variables in Tags

Create smart tags with dynamic content:

```
/response create name:closing content:Thanks {ticket.user}! Ticket #{ticket.number} is now closed. Contact us anytime at {server.name}!
```

Available variables:
- `{ticket.user}`, `{ticket.email}`, `{ticket.number}`, `{ticket.subject}`
- `{staff.name}`, `{staff.mention}`
- `{server.name}`, `{date}`, `{time}`

## 7. Priority Management

Set priorities for better organization:

```
/priority low      # 🟢 Low priority
/priority normal   # 🟡 Normal (default)
/priority medium   # 🟠 Medium priority
/priority high     # 🔴 High priority (sends email to ticket sender)
```
The bot posts: *Your ticket has been upgraded/downgraded to [Emoji][Level][Emoji].* or *Your ticket priority has returned to Normal.*

## 8. Test the Panel System

1. Create panel in a channel: `/panel #support`
2. As a user, click "Open Ticket" button
3. Fill out the modal form
4. Submit → Ticket channel created automatically!

## 9. View All Commands

```
/help
```

Shows organized list of all commands with descriptions.

## 10. Check Your Setup

Verify everything is working:

✅ All slash commands appear in Discord
✅ Can create saved responses with `/response create`; use `/tag` for ticket category
✅ Panel shows "Open Ticket" button (and optional type: thread / category / both)
✅ Clicking button shows modal form
✅ Close button shows confirmation
✅ Priority command updates ticket
✅ `/help` command shows all features

---

## Common Issues

### Commands not showing?
- Wait up to 1 hour for Discord to sync
- Verify `DISCORD_APPLICATION_ID` in `.env`
- Restart bot

### Modal not appearing?
- Check user permissions
- Ensure bot has proper guild permissions
- Try in different channel

### Saved responses not working?
- Use `/response list` to see all tags
- Check for typos in tag name
- Autocomplete shows valid tags

---

## Next Steps

1. **Create More Tags**: Add responses for common questions
2. **Set Up Panels**: Put panels in help channels
3. **Train Staff**: Show team the new commands
4. **Enable Auto-Features**: Turn on auto-unclaim if desired
5. **Customize Messages**: Edit `.env` variables for your brand
6. **Monitor Performance**: Check logs for errors

---

## Key Features Summary

✨ **Variables** - Dynamic message templates  
🏷️ **Tags** - Saved responses system  
👥 **User Management** - Add/remove users from tickets  
🎫 **Panel System** - User-friendly ticket creation  
📋 **Modal Forms** - Interactive ticket submission  
⚡ **Priority Levels** - Organize by importance  
🔄 **Transfer** - Move tickets between staff  
📌 **Enhanced Claiming** - Auto-unclaim, overwrite options  
✅ **Close Confirmation** - Prevent accidental closes  
📚 **Help Command** - Built-in documentation  

---

## Pro Tips

💡 Use variables in welcome messages for personalization  
💡 Create tags for FAQs to save time  
💡 Set high priority for urgent tickets  
💡 Use `/topic` to document ticket status  
💡 Enable auto-unclaim to prevent stale claims  
💡 Put panels in pinned messages  
💡 Use `/transfer` with reasons for context  

---

## Getting Help

- Read [PHASE_FEATURES.md](./PHASE_FEATURES.md) for detailed documentation
- Check logs for error messages
- Test features in a test channel first
- Use `/help` in Discord for command reference

---

**Ready to go! Enjoy your enhanced ticket system! 🚀**