Enhance device management documentation for MCP configuration, emphasizing automatic registration, security, and multi-device support.

Author: Lasim

docs/device-management.mdx

@@ -0,0 +1,303 @@
+---
+title: Device Management
+description: Understand how DeployStack manages devices across your organization for security, compliance, and seamless multi-device MCP configuration workflows.
+sidebar: Device Management
+icon: Monitor
+---
+
+# Device Management
+
+DeployStack automatically tracks and manages devices across your organization to enable secure multi-device MCP configurations, enterprise governance, and seamless user experiences. Every device that accesses DeployStack is registered and managed through our comprehensive device management system.
+
+## Why Device Management Matters
+
+Device management is essential for DeployStack's three-tier MCP configuration system and enterprise security:
+
+**🏢 Enterprise Governance**
+- **Visibility**: Administrators can see which devices access which MCP servers across the organization
+- **Compliance**: Complete audit trails for regulatory requirements and security policies
+- **Access Control**: Ability to manage and revoke device access when needed
+- **Risk Management**: Identify and respond to unauthorized or compromised devices
+
+**👥 Team Collaboration**
+- **Multi-Device Workflows**: Users seamlessly work across laptops, desktops, and cloud workstations
+- **Device-Specific Configurations**: Different MCP settings for different environments (development vs. production machines)
+- **Team Visibility**: Team administrators can see device usage patterns and optimize configurations
+
+**🔒 Security & Trust**
+- **Device Authentication**: Each device is uniquely identified and authenticated
+- **Hardware Fingerprinting**: Secure device identification based on system characteristics
+- **Trust Management**: Mark devices as trusted or untrusted based on organizational policies
+- **Automatic Registration**: Devices are registered securely during OAuth2 login flow
+
+## How Device Registration Works
+
+Device registration happens automatically and securely during the CLI login process:
+
+### Automatic Registration Process
+
+1. **User Initiates Login**: User runs `deploystack login` command
+2. **OAuth2 Flow Begins**: Standard OAuth2 authorization with PKCE security
+3. **Device Detection**: Gateway automatically detects device information:
+   - Device name (hostname)
+   - Hardware fingerprint (unique identifier based on MAC addresses and system info)
+   - Operating system and version
+   - System architecture
+   - Node.js version for compatibility
+4. **Secure Registration**: Device info is included in OAuth2 token exchange
+5. **Backend Processing**: Device is registered or updated in the database
+6. **User Confirmation**: User sees "📱 Device registered: [device-name]" message
+
+### Security Benefits of Integrated Registration
+
+- **No Separate Endpoints**: Device registration only happens during authenticated login sessions
+- **OAuth2 Security**: Leverages existing OAuth2 security with PKCE
+- **Hardware Fingerprinting**: Unique device identification without user input
+- **Automatic Process**: No manual device management required
+
+For technical details on the OAuth2 integration, see [Gateway OAuth Implementation](/development/gateway/oauth#automatic-device-registration).
+
+## Device Information Collected
+
+DeployStack collects minimal device information necessary for identification and configuration management:
+
+**🔍 Device Identification**
+- **Device Name**: User-friendly name (defaults to hostname, can be customized)
+- **Hardware ID**: Unique fingerprint based on MAC addresses and system characteristics
+- **Hostname**: System hostname for identification
+
+**💻 System Information**
+- **Operating System**: Type and version (macOS, Windows, Linux)
+- **Architecture**: System architecture (x64, arm64, etc.)
+- **Node.js Version**: For compatibility tracking and troubleshooting
+- **User Agent**: CLI version and platform information
+
+**📊 Usage Metadata**
+- **Last Login**: When the device was last used for authentication
+- **Last Activity**: Most recent MCP server interaction
+- **Trust Status**: Whether the device is marked as trusted
+- **Active Status**: Whether the device is currently active
+
+## Multi-Device User Experience
+
+Users can seamlessly work across multiple devices with device-specific configurations:
+
+### Device-Specific MCP Configurations
+
+Each device maintains its own personal MCP configuration while inheriting team settings:
+
+**Example: Filesystem MCP Server**
+- **MacBook Pro**: `/Users/alice/Development`, `/Users/alice/Projects`
+- **Work Desktop**: `C:\Users\alice\Projects`, `C:\Company\Shared`
+- **Cloud Workstation**: `/home/alice/workspace`, `/data/projects`
+
+**Shared Team Settings** (inherited on all devices):
+- Team API keys and credentials
+- Shared project directories
+- Team-wide configuration standards
+
+### Device Management Interface
+
+Users can manage their devices through the DeployStack interface:
+
+```
+Your Devices
+
+📱 MacBook Pro (Current Device)
+   ├─ Last Login: 2 minutes ago
+   ├─ Status: Active, Trusted
+   ├─ MCP Configurations: 5 active
+   └─ [Configure] [View Details]
+
+🖥️ Work Desktop
+   ├─ Last Login: Yesterday
+   ├─ Status: Active, Trusted
+   ├─ MCP Configurations: 3 active
+   └─ [Configure] [View Details]
+
+☁️ Cloud Workstation
+   ├─ Last Login: 3 days ago
+   ├─ Status: Inactive
+   ├─ MCP Configurations: 2 configured
+   └─ [Configure] [Reactivate]
+```
+
+## Administrator Perspective
+
+### Enterprise Device Visibility
+
+Administrators have comprehensive visibility into device usage across the organization:
+
+**📊 Device Analytics Dashboard**
+- Total devices across all teams
+- Active vs. inactive device counts
+- Device types and operating systems
+- MCP server usage by device
+- Security alerts and untrusted devices
+
+**🔍 Device Search and Filtering**
+- Search by user, team, or device name
+- Filter by operating system, trust status, or activity
+- View device-specific MCP configurations
+- Export device reports for compliance
+
+### Security Management
+
+**🛡️ Device Trust Management**
+- Mark devices as trusted or untrusted
+- Automatically trust devices from known networks
+- Require manual approval for new devices
+- Bulk trust management for organizational devices
+
+**🚨 Security Monitoring**
+- Detect unusual device activity patterns
+- Alert on new device registrations
+- Monitor for potential security threats
+- Track device access to sensitive MCP servers
+
+**⚙️ Device Policies**
+- Set maximum devices per user
+- Require device naming conventions
+- Enforce device trust requirements
+- Configure automatic device cleanup policies
+
+## Team Administrator Perspective
+
+### Team Device Overview
+
+Team administrators can monitor device usage within their teams:
+
+**👥 Team Device Dashboard**
+- All devices used by team members
+- Device-specific MCP configuration usage
+- Team member device patterns
+- Device compliance with team policies
+
+**📈 Usage Analytics**
+- Which MCP servers are used on which devices
+- Device-specific configuration patterns
+- Team productivity insights
+- Resource utilization by device type
+
+### Device-Aware Configuration Management
+
+Team administrators can optimize configurations based on device usage:
+
+**💡 Configuration Insights**
+- See how team members configure MCP servers across different devices
+- Identify common device-specific patterns
+- Optimize team configurations for different device types
+- Provide device-specific guidance and templates
+
+## Security & Governance
+
+### Compliance Benefits
+
+**📋 Audit Trails**
+- Complete history of device access to MCP servers
+- Track configuration changes by device
+- Monitor team member device usage patterns
+- Generate compliance reports for auditors
+
+**🔐 Access Control**
+- Revoke access for lost or stolen devices
+- Temporarily disable suspicious devices
+- Enforce device trust requirements
+- Control device access to sensitive MCP servers
+
+### Data Protection
+
+**🛡️ Device Security**
+- Hardware fingerprinting prevents device spoofing
+- Encrypted device information storage
+- Secure device authentication
+- Protection against unauthorized device access
+
+**🔒 Privacy Controls**
+- Minimal device information collection
+- User control over device naming
+- Secure storage of device metadata
+- Clear data retention policies
+
+For platform-level device security details, see [Security and Privacy](/security#device-security).
+
+## Device Lifecycle Management
+
+### Device States
+
+**✅ Active Devices**
+- Recently used for MCP server access
+- Receiving configuration updates
+- Included in team analytics
+- Full access to team MCP installations
+
+**⏸️ Inactive Devices**
+- Not used recently (configurable threshold)
+- Configurations preserved but not updated
+- Excluded from active analytics
+- Can be reactivated by user login
+
+**🚫 Disabled Devices**
+- Manually disabled by administrators
+- No access to MCP servers
+- Configurations preserved for potential reactivation
+- Requires administrator action to re-enable
+
+**🗑️ Removed Devices**
+- Permanently removed from the system
+- All configurations deleted
+- Cannot be recovered
+- Audit trail preserved for compliance
+
+### Automatic Cleanup
+
+**⏰ Inactive Device Management**
+- Automatically mark devices inactive after configurable period
+- Send notifications before marking devices inactive
+- Preserve configurations for potential reactivation
+- Clean up truly abandoned devices
+
+**🧹 Data Retention**
+- Remove device data after extended inactivity
+- Preserve audit trails for compliance requirements
+- User notification before permanent deletion
+- Administrator override for important devices
+
+## Integration with MCP Configuration System
+
+Device management is deeply integrated with DeployStack's three-tier MCP configuration system:
+
+### Device-Specific User Configurations
+
+The user tier of the configuration system is inherently device-aware:
+
+- **Template Level**: Global admin defines what can be configured (device-independent)
+- **Team Level**: Team admin sets shared settings (inherited by all user devices)
+- **User Level**: Individual users configure personal settings **per device**
+
+For complete details on the three-tier system, see [MCP Configuration System](/mcp-configuration).
+
+### Configuration Assembly by Device
+
+When a user accesses MCP servers, configurations are assembled per device:
+
+```
+Final Configuration = Template + Team + User (This Device)
+
+Template (Global): Command, package, system flags
++ Team (Shared): API keys, shared directories, team standards
++ User Device (Personal): Device-specific paths, preferences, debug settings
+= Runtime Configuration for This Device
+```
+
+## Related Documentation
+
+For complete understanding of device management in context:
+
+- [MCP Configuration System](/mcp-configuration) - How device-specific configurations work within the three-tier system
+- [MCP User Configuration](/mcp-user-configuration) - User experience for multi-device configuration
+- [Security and Privacy](/security) - Platform-level device security implementation
+- [Gateway OAuth Implementation](/development/gateway/oauth) - Technical details of device registration during login
+- [Teams](/teams) - Team structure and device visibility for team administrators
+
+Device management enables DeployStack to provide secure, scalable, and user-friendly MCP server management across any number of devices while maintaining enterprise-grade governance and compliance capabilities.

docs/mcp-configuration.mdx

@@ -14,9 +14,9 @@ The system separates configuration into three distinct layers:
 
 1. **Template Level** - Global schemas and locked elements defined by administrators
 2. **Team Level** - Shared team configurations with lock/unlock controls  
-3. **User Level** - Personal configurations within team-defined boundaries
+3. **User Level** - Personal configurations within team-defined boundaries **per device**
 
-This architecture enables teams to share common settings like API keys while allowing individual members to customize personal settings like local file paths.
+This architecture enables teams to share common settings like API keys while allowing individual members to customize personal settings like local file paths across multiple devices. Each user can have different configurations on different devices while maintaining team security and standards.
 
 ## How It Works
 
@@ -42,11 +42,12 @@ This architecture enables teams to share common settings like API keys while all
                                         │
                                         ▼
 ┌─────────────────────────────────────────────────────────────────────────────────┐
-│ TIER 3: USER (Individual)                                                      │
+│ TIER 3: USER (Individual) - Device-Aware                                      │
 │ ┌─────────────────────────────────────────────────────────────────────────────┐ │
-│ │ 🔓 Personal Settings: Local paths, preferences                             │ │
-│ │ 💻 Multi-Device: Different configs per device                              │ │
-│ │ 🔗 Automatic Inheritance: Use team credentials seamlessly                  │ │
+│ │ 🔓 Personal Settings: Local paths, preferences (per device)                │ │
+│ │ 💻 Multi-Device: Different configs per device with automatic registration   │ │
+│ │ 🔗 Automatic Inheritance: Use team credentials seamlessly across devices    │ │
+│ │ 🛡️ Device Security: Hardware fingerprinting and secure registration        │ │
 │ └─────────────────────────────────────────────────────────────────────────────┘ │
 └─────────────────────────────────────────────────────────────────────────────────┘
                                         │
@@ -75,9 +76,10 @@ The heart of the system is sophisticated lock/unlock controls with precise categ
 
 **User Access:**
 - **Personal Customization** - Modify only unlocked elements within boundaries set by global admin categorization
-- **Device-Specific Settings** - Configure personal settings across multiple devices
+- **Device-Specific Settings** - Configure personal settings across multiple devices with automatic device registration
 - **Secure Experience** - No access to locked configuration, team secrets, or template elements
 - **Focused Interface** - See only configuration elements designated as personally configurable
+- **Multi-Device Workflow** - Seamlessly work across different devices with device-specific configurations
 
 ## User Journey Workflows
 
@@ -118,7 +120,7 @@ Here's how the three tiers combine into a final runtime configuration:
 }
 ```
 
-**User (Individual):**
+**User (Individual - i.e.: your MacBook Pro):**
 ```json
 {
   "args": ["/Users/alice/Development", "/Users/alice/Projects"],
@@ -164,12 +166,34 @@ Here's how the three tiers combine into a final runtime configuration:
 
 **Support Teams:** Share customer service API keys while allowing personal workspace customization
 
+## Device-Aware Architecture Benefits
+
+**🏢 Enterprise Governance**
+- Complete visibility into device usage across the organization
+- Device-specific audit trails for compliance and security
+- Centralized device management with trust-based access control
+
+**👥 Team Collaboration**
+- Team administrators can see device usage patterns and optimize configurations
+- Device-specific insights help teams understand productivity patterns
+- Seamless collaboration across different device types and environments
+
+**🔒 Enhanced Security**
+- Hardware fingerprinting prevents device spoofing
+- Automatic device registration during secure OAuth2 login
+- Device trust management and access revocation capabilities
+- No separate device registration endpoints (security by design)
+
+For comprehensive device management details, see [Device Management](/device-management).
+
 ## Related Documentation
 
 For complete system understanding:
 
+- [Device Management](/device-management) - Comprehensive device management and security
 - [MCP Catalog](/mcp-catalog) - Browse and discover available MCP servers
 - [Teams](/teams) - Team structure and membership management
 - [MCP Installation](/mcp-installation) - Basic MCP server installation concepts
+- [Security and Privacy](/security) - Platform security including device security
 
-The three-tier configuration system provides secure, scalable MCP server management that grows from individual developers to enterprise teams while maintaining simplicity and security at every level. Global administrators have sophisticated control over configuration boundaries through schema categorization, ensuring appropriate access and customization at each tier.
+The three-tier configuration system provides secure, scalable MCP server management that grows from individual developers to enterprise teams while maintaining simplicity and security at every level. Global administrators have sophisticated control over configuration boundaries through schema categorization, ensuring appropriate access and customization at each tier. The device-aware architecture enables seamless multi-device workflows while maintaining enterprise-grade security and governance.