TEAM_COLLABORATION_GUIDE.md

# Team Collaboration Guide - MCP 1st Birthday Hackathon

## Overview

This guide explains how to add team partners to your FleetMind MCP hackathon submission on Hugging Face Spaces.

**Hackathon Details:**
- **Team Size:** 2-5 members allowed
- **Your Space:** https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai
- **Submission Deadline:** November 30, 2025 (11:59 PM UTC)
- **Track:** MCP in Action (Track 01)

---

## Method 1: Add Team Members via README Documentation (EASIEST)

For hackathon submission purposes, you MUST document your team in the Space's README.md file.

### Steps:

1. **Edit the Team Section in README.md**

   The Team section is already added to your README. Update it with your actual team information:

   ```markdown
   ## 👥 Team

   **Team Name:** FleetMind AI Team

   **Team Members:**
   - **John Doe** - [@johndoe](https://huggingface.co/johndoe) - Lead Developer & AI Architect
   - **Jane Smith** - [@janesmith](https://huggingface.co/janesmith) - Database Engineer
   - **Alex Chen** - [@alexchen](https://huggingface.co/alexchen) - UI/UX Developer
   ```

2. **Replace Placeholders:**
   - `[Your Team Name]` → Your actual team name
   - `[Your Name]` → Team member's real name
   - `@your-hf-username` → Their Hugging Face username
   - `[Role]` → Their role in the project

3. **Commit and Push:**

   ```bash
   cd F:\fleetmind-mcp\fleetmind-dispatch-ai
   git add README.md
   git commit -m "Update team member information"
   git push
   ```

---

## Method 2: Grant Git Access to Team Partners (TECHNICAL COLLABORATION)

If your team partners need to push code directly to the Space, they need Git access.

### Option A: Via Organization Membership

Since your Space is owned by the **MCP-1st-Birthday organization**, team members can:

1. **Join the Organization:**
   - Go to https://huggingface.co/MCP-1st-Birthday
   - Click **"Request to join this org"** (top right)
   - Fill out the registration form
   - Wait for admin approval

2. **Verify Access:**
   - Once approved, they'll automatically have access based on organization permissions
   - Organization members with "write" or "contributor" roles can collaborate

### Option B: Direct Collaborator Access

If you have admin rights to your Space:

1. **Go to Space Settings:**
   - Visit: https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai/settings
   - Look for "Collaborators" or "Access" section

2. **Add Collaborators by Username:**
   - Enter their Hugging Face username
   - Set their permission level (read/write/admin)
   - Send invitation

---

## Method 3: Collaborate via Pull Requests (SAFEST)

Team members can contribute without direct write access using Pull Requests.

### Steps:

1. **Team Partner Forks/Duplicates the Space:**
   - They go to your Space page
   - Click the three dots (top right) → "Duplicate this Space"
   - Make changes in their forked version

2. **Create Pull Request:**
   - After making changes, they create a Pull Request
   - You review and merge their changes

3. **Enable Pull Requests:**
   - Go to Space Settings
   - Ensure "Pull Requests" are enabled

---

## Method 4: Share Git Credentials (NOT RECOMMENDED)

While technically possible, sharing your Git credentials is NOT recommended for security reasons. Use Methods 1-3 instead.

---

## Technical Setup for Team Partners

Once your team partners have access, they need to set up their local environment:

### 1. Clone the Space

```bash
# Navigate to desired directory
cd F:\

# Clone the Space
git clone https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai

# Enter directory
cd fleetmind-dispatch-ai
```

### 2. Authenticate with Hugging Face

They need a Hugging Face access token:

1. **Get Token:**
   - Go to https://huggingface.co/settings/tokens
   - Click "New token"
   - Create a token with "write" permissions

2. **Login via CLI:**
   ```bash
   # Install Hugging Face CLI
   pip install huggingface_hub

   # Login (they'll be prompted for token)
   huggingface-cli login
   ```

3. **Or Configure Git Credentials:**
   ```bash
   git config credential.helper store
   ```

   When they push for the first time, Git will ask for:
   - Username: Their HF username
   - Password: Their HF access token (NOT their account password)

### 3. Make Changes and Push

```bash
# Make changes to files
# ...

# Stage changes
git add .

# Commit
git commit -m "Add feature X"

# Push to Space
git push
```

---

## Hugging Face Spaces Access Levels

Understanding permission levels helps you decide what access to grant:

| Role | Can View | Can Clone | Can Push | Can Manage Settings |
|------|----------|-----------|----------|---------------------|
| **Public** | ✅ | ✅ | ❌ | ❌ |
| **Read** | ✅ | ✅ | ❌ | ❌ |
| **Contributor** | ✅ | ✅ | Via PR only | ❌ |
| **Write** | ✅ | ✅ | ✅ | ❌ |
| **Admin** | ✅ | ✅ | ✅ | ✅ |

---

## Hackathon Submission Requirements

For your team submission to be valid, ensure:

### Required in README.md:
- ✅ **Team section** with all member names and HF usernames
- ✅ **Track tag:** `mcp-in-action-track-01` (already added)
- ✅ **Demo video link** (1-5 minutes) - TODO
- ✅ **Social media post link** - TODO

### Required in Space:
- ✅ Published as a Space in MCP-1st-Birthday organization
- ✅ App.py entry point (already created)
- ✅ Working Gradio interface
- ✅ All code created during hackathon period (Nov 14-30, 2025)

---

## Troubleshooting

### "Permission denied" when team partner tries to push

**Solution:**
1. Verify they're added as collaborators with write access
2. Check they're using the correct HF access token (not account password)
3. Ensure token has "write" permissions

### "Repository not found" error

**Solution:**
1. Verify the Space URL is correct
2. Check they have at least "read" access
3. Ensure they're logged in: `huggingface-cli whoami`

### Team member can't see the Space

**Solution:**
1. If Space is private, add them as collaborators
2. If Space is public (recommended for hackathon), they should see it
3. Check organization membership status

---

## Best Practices for Team Collaboration

1. **Communication:**
   - Use Discord channel: agents-mcp-hackathon-winter25
   - Create a team group chat
   - Document decisions in README

2. **Code Management:**
   - Pull before making changes: `git pull`
   - Commit frequently with clear messages
   - Test locally before pushing

3. **Task Distribution:**
   - Assign specific files/features to team members
   - Avoid editing the same files simultaneously
   - Use TODO comments in code

4. **Version Control:**
   - Create branches for major features (optional)
   - Use descriptive commit messages
   - Review each other's code

---

## Quick Reference Commands

```bash
# Clone the Space
git clone https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai

# Check current status
git status

# Pull latest changes
git pull

# Add all changes
git add .

# Commit with message
git commit -m "Description of changes"

# Push to Space
git push

# Check who you're logged in as
huggingface-cli whoami

# Login to HF
huggingface-cli login
```

---

## Support & Resources

- **Hackathon Discord:** agents-mcp-hackathon-winter25 channel
- **Office Hours:** November 17-28 with Gradio team
- **HF Documentation:** https://huggingface.co/docs/hub/spaces
- **Git Documentation:** https://git-scm.com/doc

---

## Timeline Reminder

- **Start Date:** November 14, 2025
- **Submission Deadline:** November 30, 2025 (11:59 PM UTC)
- **Days Remaining:** Check dashboard regularly

Make sure all team members are added to README.md before the deadline!

---

**Good luck with your hackathon submission! 🚀**