Enhance team management documentation: clarify multi-user support, member management permissions, and default team restrictions.

Author: Lasim

docs/deploystack/development/backend/roles.mdx

@@ -74,15 +74,16 @@ The RBAC system provides fine-grained access control through roles and permissio
 
 ## Team System
 
-DeployStack includes a comprehensive team management system that allows users to organize their work into teams. Each user automatically gets their own team upon registration and can create up to 3 teams total.
+DeployStack includes a comprehensive team management system that allows users to organize their work into teams and collaborate with other users. Each user automatically gets their own team upon registration and can create up to 3 teams total.
 
 ### Team Features
 
 - **Automatic Team Creation**: Every new user gets a default team created with their username
 - **Team Ownership**: Each team has an owner who has full administrative control
-- **Single User Teams**: Currently, teams support only one user per team
+- **Multi-User Teams**: Teams support up to 3 members with role-based access control
 - **Team Limits**: Users can create up to 3 teams maximum
 - **Unique Slugs**: Teams have URL-friendly slugs with automatic conflict resolution
+- **Default Team Protection**: Default teams cannot have additional members added (personal workspace)
 
 ### Team Database Schema
 
@@ -301,6 +302,95 @@ GET /api/teams/:id/members
 Authorization: Required (team.members.view permission)
 ```
 
+**Response:**
+
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "membership123",
+      "user_id": "user123",
+      "username": "johndoe",
+      "email": "john@example.com",
+      "first_name": "John",
+      "last_name": "Doe",
+      "role": "team_admin",
+      "is_admin": true,
+      "is_owner": true,
+      "joined_at": "2025-01-30T15:00:00.000Z"
+    }
+  ]
+}
+```
+
+#### Add Team Member
+
+```http
+POST /api/teams/:id/members
+Authorization: Required (team.members.manage permission or global admin)
+Content-Type: application/json
+
+{
+  "userId": "user456",
+  "role": "team_user"
+}
+```
+
+**Restrictions:**
+- Maximum 3 members per team
+- Cannot add members to default teams (protected)
+- User must exist in the system
+- Team admin or global admin required
+
+#### Update Team Member Role
+
+```http
+PUT /api/teams/:id/members/:userId/role
+Authorization: Required (team.members.manage permission or global admin)
+Content-Type: application/json
+
+{
+  "role": "team_admin"
+}
+```
+
+**Restrictions:**
+- Cannot change roles in default teams
+- Must maintain at least one team admin
+- Team admin or global admin required
+
+#### Remove Team Member
+
+```http
+DELETE /api/teams/:id/members/:userId
+Authorization: Required (team.members.manage permission or global admin)
+```
+
+**Restrictions:**
+- Cannot remove from default teams
+- Cannot remove team owner (must transfer ownership first)
+- Cannot remove last member from team
+- Team admin or global admin required
+
+#### Transfer Team Ownership
+
+```http
+PUT /api/teams/:id/ownership
+Authorization: Required (team owner or global admin)
+Content-Type: application/json
+
+{
+  "newOwnerId": "user456"
+}
+```
+
+**Restrictions:**
+- Cannot transfer ownership of default teams
+- New owner must be a team member
+- New owner automatically becomes team_admin
+- Only current owner or global admin can transfer
+
 ### Team Service Methods
 
 The `TeamService` class provides comprehensive team management:
@@ -341,6 +431,38 @@ const isDefault = await TeamService.isDefaultTeam(teamId, userId);
 
 // Get team membership details
 const membership = await TeamService.getTeamMembership(teamId, userId);
+
+// ===== TEAM MEMBER MANAGEMENT METHODS =====
+
+// Add team member
+const membership = await TeamService.addTeamMember(teamId, userId, 'team_user');
+
+// Remove team member
+const removed = await TeamService.removeTeamMember(teamId, userId);
+
+// Update member role
+const updatedMembership = await TeamService.updateMemberRole(teamId, userId, 'team_admin');
+
+// Transfer team ownership
+const transferred = await TeamService.transferOwnership(teamId, newOwnerId);
+
+// Get team members with user info
+const membersWithInfo = await TeamService.getTeamMembersWithUserInfo(teamId);
+
+// Get user teams with role info
+const teamsWithRoles = await TeamService.getUserTeamsWithRoles(userId);
+
+// Team capacity and permission checks
+const canAddMember = await TeamService.canAddMemberToTeam(teamId);
+const canRemoveMember = await TeamService.canRemoveMemberFromTeam(teamId, userId);
+const canManageMember = await TeamService.canUserManageTeamMember(teamId, managerId, targetUserId, 'add');
+
+// Team member counts
+const memberCount = await TeamService.getTeamMemberCount(teamId);
+const adminCount = await TeamService.getTeamAdminCount(teamId);
+
+// Default team protection checks
+const isTeamDefault = await TeamService.isTeamDefault(teamId);
 ```
 
 ### Frontend Team Management

docs/deploystack/roles.mdx

@@ -45,8 +45,37 @@ User roles determine what actions a person can perform in DeployStack. Think of
 **What they can do**:
 - Manage their team's settings
 - View team members
+- **Add new members to their teams** (up to 3 members total)
+- **Change member roles** (promote team_user to team_admin, or demote)
+- **Remove team members** (except team owners)
+- **Transfer team ownership** to another team member
 - Manage team deployments
-- Delete teams they own
+- Delete teams they own (except default teams)
+
+**Important**: Team admins have full control over team membership and can manage all team members except the team owner.
+
+## Team Member Management Permissions
+
+The following table shows exactly what each role can do with team member management:
+
+| Action | team_user | team_admin | team_admin + owner | global_admin |
+|--------|-----------|------------|-------------------|--------------|
+| List team members | ✅ (own teams) | ✅ (own teams) | ✅ (own teams) | ✅ (any team) |
+| Add team member | ❌ | ✅ (non-default) | ✅ (non-default) | ✅ (any team) |
+| Remove team_user | ❌ | ✅ (non-default) | ✅ (non-default) | ✅ (any team) |
+| Remove team_admin | ❌ | ❌ | ✅ (non-default) | ✅ (any team) |
+| Remove team owner | ❌ | ❌ | ❌ | ✅ (any team) |
+| Promote to team_admin | ❌ | ✅ (non-default) | ✅ (non-default) | ✅ (any team) |
+| Demote team_admin | ❌ | ❌ | ✅ (non-default) | ✅ (any team) |
+| Transfer ownership | ❌ | ❌ | ✅ (non-default) | ✅ (any team) |
+| Delete team | ❌ | ❌ | ✅ (non-default) | ✅ (non-default) |
+
+**Key Notes:**
+- **Default teams** are completely protected - no member management operations allowed
+- **Team admins** can only manage team_users, not other team_admins or owners
+- **Team owners** have full control over their teams (except default teams)
+- **Global admins** can override most restrictions but still cannot modify default teams
+- **3-member limit** applies to all teams (owner + 2 additional members maximum)
 
 ### Team User
 **Who needs this**: Basic team members who participate in deployments.
@@ -56,6 +85,8 @@ User roles determine what actions a person can perform in DeployStack. Think of
 - See team members
 - Participate in team activities
 
+**Limitations**: Team users cannot add members, change roles, or manage other team members.
+
 ## Understanding Teams
 
 Teams are groups where users organize their deployment projects. Here's how teams work:

docs/deploystack/teams.mdx

@@ -16,6 +16,8 @@ In DeployStack, teams provide:
 - **Resource Organization**: All your MCP servers, credentials, and settings are organized within teams
 - **Access Control**: Team-based permissions ensure secure access to your deployment resources
 - **Multi-Project Support**: Create up to 3 teams to organize different projects or environments
+- **Team Collaboration**: Teams support multiple members with role-based access control
+- **Default Team Protection**: Your personal default team cannot have additional members added
 
 Every team acts as a complete deployment environment, containing everything needed to deploy and manage MCP servers across various cloud providers.
 
@@ -135,22 +137,95 @@ The interface provides clear visual feedback:
 
 ### Current Structure
 
-DeployStack teams currently operate with a **single-user model**:
+DeployStack teams support **multi-user collaboration** with role-based access control:
 
-- Each team belongs to one user
-- You have full control over your teams
-- No team sharing or collaboration features (planned for future releases)
+- Teams can have up to **3 members maximum**
+- Each team has one **owner** who created the team
+- Team members can have different roles with specific permissions
+- **Default teams are personal** - no additional members can be added to your default team
 
 ### Team Roles
 
-Within your teams, you automatically have the **Team Administrator** role, which provides:
+Teams support two distinct roles with different capabilities:
 
-- Full access to all team resources
-- Ability to deploy and manage MCP servers
-- Permission to modify team settings
-- Authority to delete the team
+#### Team Administrator
+- **Full team management**: Can add/remove members, change roles, transfer ownership
+- **Resource access**: Full access to all team resources and deployments
+- **Team settings**: Can modify team name, description, and all configurations
+- **Member management**: Can promote team users to admins or demote admins to users
 
-*Note: Team User roles exist in the system for future multi-user team functionality.*
+#### Team User
+- **Basic access**: Can view team information and see team members
+- **Limited permissions**: Cannot add members, change roles, or modify team settings
+- **Resource viewing**: Can see team resources but with restricted management capabilities
+
+**Important**: Your **default team** (created automatically with your username) is protected - you cannot add other members to it. This keeps your personal workspace private.
+
+## Team Member Management
+
+### Adding Team Members
+
+Team administrators can add new members to their teams (except default teams):
+
+1. **Navigate to Team Management**: Go to your team's management page
+2. **Find Members Section**: Look for the team members management area
+3. **Add Member**: Click "Add Member" and enter the user's email or username
+4. **Assign Role**: Choose either "Team Administrator" or "Team User"
+5. **Send Invitation**: The user will be notified and added to the team
+
+**Limitations**:
+- **Maximum 3 members** per team (including the owner)
+- **Default teams**: Cannot add members to your personal default team
+- **Existing users only**: Can only add users who already have DeployStack accounts
+
+### Managing Member Roles
+
+Team administrators and owners can change member roles:
+
+#### Promoting Team Users to Administrators
+- **Who can do this**: Team administrators and team owners
+- **Process**: Select the member and change their role to "Team Administrator"
+- **Result**: User gains full team management capabilities
+
+#### Demoting Team Administrators to Users
+- **Who can do this**: Team owners (and other team administrators)
+- **Restriction**: Must maintain at least one team administrator
+- **Process**: Change the administrator's role to "Team User"
+
+### Removing Team Members
+
+Team administrators can remove members from teams:
+
+- **Who can remove**: Team administrators and owners
+- **Cannot remove**: Team owners (must transfer ownership first)
+- **Default teams**: No members to remove (single-user only)
+- **Process**: Select member and click "Remove from Team"
+
+### Transferring Team Ownership
+
+Team owners can transfer ownership to another team member:
+
+1. **Requirement**: Target user must already be a team member
+2. **Process**: Go to team settings and select "Transfer Ownership"
+3. **Choose New Owner**: Select from existing team administrators
+4. **Confirm Transfer**: Confirm the ownership change
+5. **Result**: New owner gains full control, previous owner becomes team administrator
+
+**Important**: 
+- **Cannot transfer default team ownership** - default teams always belong to the original user
+- **Irreversible action** - ownership transfers cannot be undone
+- **New owner requirements** - Target user must be a team administrator
+
+### Default Team Restrictions
+
+Your automatically created default team has special protections:
+
+- **No Additional Members**: Cannot add other users to your default team
+- **Cannot Transfer Ownership**: Default team ownership cannot be changed
+- **Cannot Leave**: You cannot leave your own default team
+- **Personal Workspace**: Designed to remain your private workspace
+
+These restrictions ensure that every user always has a personal, private team for their individual work.
 
 ### Resource Isolation