gh-christianlouis-leagueledger/docs/user-guide/teams.md

# Teams

Teams are a core feature of LeagueLedger, allowing users to form groups that compete and collaborate. This guide explains how to create, join, and manage teams within the system.

## Teams Overview

In LeagueLedger, teams provide a way for users to:

- Collaborate toward common goals
- Compete against other teams
- Share resources and achievements
- Track collective progress

Each team has:

- A unique name and profile
- A team owner (creator by default)
- Team members with different roles
- A team points total (sum of members' contributions)
- Team-specific achievements and stats

## Creating a Team

### Basic Team Creation

To create a new team:

1. Log in to your LeagueLedger account
2. Navigate to the "Teams" section from the main menu
3. Click the "Create New Team" button
4. Fill in the required information:
   - Team name (unique within the system)
   - Short description
   - Team logo (optional)
5. Select team visibility:
   - Public: Visible to all users
   - Private: Visible only to members and invitees
6. Choose join settings:
   - Open: Anyone can join
   - Request: Users can request to join
   - Invite-only: Only invited users can join
7. Click "Create Team"

You'll automatically become the team owner with full administrative privileges.

### Team Settings

After creating a team, you can configure additional settings:

1. Go to your team page
2. Click on "Team Settings" (visible to team owners and admins)
3. Customize options such as:
   - Banner image
   - Team biography
   - Contact information
   - Social media links
   - Team rules or guidelines

## Joining Teams

### Finding Teams to Join

To discover teams you might want to join:

1. Navigate to the "Teams" section
2. Click on "Browse Teams" or "Join Team"
3. Browse available teams with options to:
   - Search by name or keywords
   - Filter by various criteria
   - Sort by size, activity, or points
4. Click on any team to view its details

### Joining an Open Team

For teams with "Open" join settings:

1. View the team details page
2. Click the "Join Team" button
3. You'll immediately be added as a member

### Requesting to Join

For teams with "Request" join settings:

1. View the team details page
2. Click "Request to Join"
3. Optional: Add a short message to the team owner
4. Submit your request
5. Wait for approval from a team admin or owner
6. You'll receive a notification when your request is approved or denied

### Joining via Invitation

If you receive a team invitation:

1. Check your notifications or email for the invitation
2. Click the invitation link
3. Review the team details
4. Click "Accept" to join or "Decline" to refuse

## Team Roles and Management

### Team Roles

LeagueLedger teams have a hierarchy of roles:

- **Owner**: The team creator with full control
- **Admin**: Can manage members and some team settings
- **Member**: Regular team participant
- **Guest**: Limited temporary access (optional feature)

### Team Member Management

As a team owner or admin, you can manage team members:

1. Go to your team page
2. Click on "Manage Members"
3. From this panel, you can:
   - Invite new members
   - Remove existing members
   - Change member roles
   - Review join requests
   - Send team announcements

### Transferring Ownership

To transfer team ownership:

1. Go to "Team Settings" > "Advanced"
2. Select "Transfer Ownership"
3. Choose a team member to become the new owner
4. Confirm the transfer

!!! warning "Irreversible Action"
    Transferring ownership cannot be undone. The new owner will have complete control over the team.

## Team Activities

### Team Points

Teams earn points when members:

- Scan QR codes
- Complete challenges
- Participate in events
- Earn achievements
- Contribute through other scoring actions

The team leaderboard reflects the cumulative points of all team members.

### Team Achievements

Teams can unlock special achievements based on:

- Total team points milestones
- Full team participation in events
- Completing special team challenges
- Consistent activity over time

Team achievements are displayed on the team profile and contribute to the team's prestige.

### Team Events

Teams can participate in events together:

1. Find an event in the "Events" section
2. Register as a team (by team owner/admin)
3. Coordinate team member participation
4. Earn team points through event activities

## Team Communication

### Team Chat

Teams have access to a built-in chat system:

1. Go to your team page
2. Click on the "Team Chat" tab
3. Send messages visible to all team members
4. Share updates, strategies, or coordinate activities

### Announcements

Team owners and admins can make official announcements:

1. Go to "Manage Members"
2. Select "Create Announcement"
3. Write your message
4. Choose notification options
5. Publish to all members

## Advanced Team Features

### Team Statistics

View detailed team performance:

1. Go to your team page
2. Select the "Statistics" tab
3. Explore metrics such as:
   - Points over time
   - Member contributions
   - Achievement progress
   - Event participation
   - Comparison with other teams

### Team Challenges

Some events feature special team challenges:

- Collaborative tasks requiring multiple team members
- Inter-team competitions
- Timed challenges with team scoring
- Special team-only QR codes

### Private Team QR Codes

Team owners can create team-specific QR codes:

1. Go to "Team Settings" > "QR Codes"
2. Select "Create Team QR"
3. Configure the code settings
4. Generate and share with team members only

These codes may offer bonus points or special achievements when scanned by team members.

## Leaving or Dissolving a Team

### Leaving a Team

To leave a team you're a member of:

1. Go to the team page
2. Click on "Team Settings" or "Manage Membership"
3. Select "Leave Team"
4. Confirm your decision

!!! note "Team Owner"
    If you're the team owner, you must first transfer ownership before leaving.

### Dissolving a Team

To completely dissolve a team (owner only):

1. Go to "Team Settings" > "Advanced"
2. Select "Dissolve Team"
3. Read the warning about this irreversible action
4. Enter your password to confirm
5. The team will be permanently removed

## Best Practices

### For Team Owners

- Establish clear team goals and guidelines
- Regularly communicate with team members
- Recognize individual contributions
- Delegate responsibilities to trusted admins
- Keep team information and graphics up-to-date

### For Team Members

- Regularly check team announcements
- Coordinate with teammates for events
- Share strategies for finding and scanning QR codes
- Help recruit quality new members
- Represent your team positively in competitions

## Troubleshooting

### Common Issues

#### Can't Find a Team

If you can't locate a specific team:
- Check if you spelled the team name correctly
- The team might be set to private visibility
- The team may have been dissolved

#### Can't Join a Team

If you're unable to join:
- The team might be invite-only
- Your request might be pending approval
- You may have reached the maximum number of teams you can join
- The team might have reached its member capacity

#### Points Not Showing for Team

If points aren't appearing:
- There may be a delay in point calculation
- Verify that your individual points are displaying correctly
- Check that you're properly affiliated with the team

## Next Steps

- [QR Codes](qr-codes.md): Learn how to earn points through QR codes
- [Points & Achievements](points-and-achievements.md): Understand the points system
- [Events](events.md): Discover how to participate in events as a team
- [Team Management](../administration/team-management.md): For administrators managing multiple teams